> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://support.robaws.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Webhooks

Navigate quickly to:
* [Using webhooks](#2-using-webhooks)
* [Verifying the signature](#2-verifying-the-signature)
* [Some considerations](#2-some-considerations)
* [Supported event types](#2-supported-event-types)


## 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](https://app.robaws.com/swagger-ui/index.html#/Webhooks/listEndpoints). 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
```json
{
    "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


## Supported event types

Currently, the following event types are supported. If you need another event, please let us know via support@robaws.com.

#### Clients
client.created
client.updated

#### Sales invoices
sales-invoice.created
sales-invoice.updated

#### Purchase invoices
purchase-invoice.created
purchase-invoice.updated

#### Offers
offer.created
offer.updated
offer.recalculated

#### Settlements
settlement.created
settlement.updated
settlement.recalculated

#### 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

#### Comments
comment.created
comment.updated

#### Sales orders
sales-order.created
sales-order.updated

#### Form answers
form-answer.created
form-answer.updated