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

Orders

sales-order.created
sales-order.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: 26/06/2024