Introduction to Webhooks

Webhook terminology

You may not be familiar with the terminology of webhooks, so here we will introduce the relevant terms as they pertain to the Worksome platform.

Webhook

A webhook is an outgoing HTTP request to your system, containing a payload of interest. Such a request is called “sending a webhook” from the Worksome side and “receiving a webhook” from your side.

Typically, a webhook is sent when a particular event happens within the sending application (in our case the Worksome platform).

Such an event may be of interest to a third party (receiving) system (such as yours), which have a need to be updated quickly after the event happens in the sending system.

A webhook is normally sent as a POST HTTP request, but could be another method. Worksome webhooks are always sent as POST requests.

To be able to receive a webhook, you must create an endpoint for it in your system, and tell us the URL of it.

Secret

The secret is a token made from a string of characters. This is exchanged between you and Worksome, and only known by those two parties. The secret is stored on both yours and Worksome systems.

It is used for signing the payload, such that you can verify that the webhook was sent from Worksome and nobody else.

The longer the secret the more secure it is. We support secrets up to 255 characters long.

Payload

A webhook payload is usually in JSON format, but could be in another format such as XML. Worksome webhooks are always in JSON format.

Headers

A widely used way of authenticating a webhook is through the use of a Signature header.

Worksome uses HMAC signatures, like GitHub, Stripe and Facebook.

Signature

The HMAC signature is created by taking the HMAC sha256 hash of the payload with the secret used as the key.

To verify the authenticity of the payload, you would take the received payload and apply the same method, using the secret, and compare your result with the contents of the Signature header. If they match, you know that Worksome was the sender.

Here is an example in PHP:

$secret = 'tHanx4allTheFish?!';

$payload = [
    'event' => 'droppedWhale',
    'data' => [
        'what' => [
            'id' => 42,
        ],
    ],
];

$payloadJson = json_encode($payload);

$signature = hash_hmac('sha256', $payloadJson, $secret);

// Signature is now: 2c25330460c6dd4af652b1c0714b5a98894aef94112b8f1e6dbd5f9830ddc766

Responses

When a webhook is received, the receiving system should respond with a 200 (or any other 2XX) HTTP code to signal that it was received without errors. If we receive any 2XX HTTP code in response to sending a webhook, we consider the webhook completely delivered.

Typical non-2XX codes might be:

  • 401 if the Signature header did not match the payload.
  • 403 if Worksome is otherwise not authorized to send to your system.
  • 404 if your system does not recognize the endpoint URL that we try to deliver to.
  • 422 in case parts of the payload failed validation, such as a worker being unknown in your system.
  • 5XX if your server crashed or is otherwise unable to handle the request. This is usually temporary.

We do not need a body in case of a 2XX code, but in any other case, we would appreciate a body in JSON format with an error message detailing the reason why it could not be received. This makes it easier for customer service to help you.

Backing off and retrying

If your system for any reason responds with other than 2XX, or the call takes longer than a timeout of 60 seconds, we start the “backing off” retry process to give your system more time to recover from whatever reason it could not receive it.

The backing off process starts by waiting 10 seconds, then tries again for a second attempt. If your system still does not respond with 2XX, or times out, then we increase the waiting time exponentially, so the third try is 100 seconds after the second, the fourth try is 1000 seconds after the third and finally the fifth attempt is 10000 seconds after the fourth.

If the fifth attempt still was not successful, we stop trying.

We log every attempt and will be able to restart the webhook sending for a particular event that ended not being successfully sent and received. Contact customer service if you suspect that you are missing a webhook.

Summary

In summary:

  • An event that you have interest in, happens in the Worksome platform.
  • Worksome creates a payload with relevant information about the event.
  • Worksome signs the payload using the agreed secret.
  • Worksome makes an HTTP POST request to the agreed endpoint at your system, with a Signature header and the payload as a JSON formatted body.
  • You receive the request and verify the payload using the secret and comparing with the Signature header.
  • When verified, perform any validations to make sure the contents fit your system.
  • If all is well, respond with a 200 HTTP code and proceed with processing the payload in your system. This might involve making a callback to our API to obtain more information.
  • Otherwise, respond with any other (non 2XX) code and preferably a body in JSON format with an error message.
  • Worksome retries sending the webhook up to a total of 5 times if your system does not respond with a 2XX code.