Artikelen over: API

Webhooks

Webhooks



Supported event types



Currently, the following event types are supported. If you need an other event, please let us know via [email protected].

Clients


client.created
client.updated

Sales invoices


sales-invoice.created
sales-invoice.updated

Offers


offer.created
offer.updated

Projects


project.created
project.updated

Articles


article.created
article.updated
article.stock-changed

Employees


employee.created
employee.updated

Planning items


planning-item.created
planning-item.updated

Work orders


work-order.created
work-order.updated

Materials


material.created
material.updated

Installations


installation.created
installation.updated

Documents


document.created
document.updated

Using webhooks



To start using webhooks with Robaws, register your webhook endpoint by doing a POST on /api/v2/webhook-endpoints. For the full request definition see the api reference docs. Please do store the secret we return to you on endpoint creation, because you will need it to verify our signatures.

After a few seconds, when your subscription becomes active, you should receive HTTP POST calls from us to the URL you specified.

This is an example of such a HTTP POST:

POST https://your-host/your-webhook-endpoint
Content-Type: application/json
Robaws-Signature: t=1674742714,v1=signature
{
    "id":"37de8552-0007-4269-a76c-06a9415c8b65",
    "event":"client.updated",
    "data": {
        ....
    }
}


Verifying the signature



It is important that you verify the signature we send in the 'Robaws-Signature' header, because otherwise you can not trust that the HTTP call is coming from Robaws. This is especially important because we are not only sending the id in the event, but the full data.

In order to verify our signature, you need the secret we returned on endpoint creation.

Step 1: extract the timestamp and the signature from the header



Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.
The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature. You can discard all other elements.
If you split those again on "=", it gives you the values you need.

Step 2: prepare the signed_payload string



The signed_payload string is created by concatenating:

The timestamp (as a string)
The character .
The actual JSON payload (that is, the request body)

Step 3: Determine the expected signature



Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message. Convert the result to hex representation.

Step 4: Compare the signatures



Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance to protect against replay attacks. To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.

Some considerations



Only admin users can register endpoints. Currently there is no UI for registering webhook endpoints. It can only be done via the API.
We consider the webhook successful when the endpoint returns an 2XX response. We will retry several times as long as your endpoint fails to responsd successfully. Our connection timeout is 2 seconds and read timeout is 2 seconds. That means, if we don't receive a response within 2 seconds, we will keep retrying the request until we do. If we never get any successful response, we may suspend your webhook without warning.
Webhooks can be tested easily using https://webhook.site

Bijgewerkt op: 13/05/2024

Was dit artikel nuttig?

Deel uw feedback

Annuleer

Dankuwel!