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

Naviguez rapidement vers :
* [Utiliser les webhooks](#2-utiliser-les-webhooks)
* [Vérifier la signature](#2-verifier-la-signature)
* [Quelques considérations](#2-quelques-considerations)
* [Types d'événements pris en charge](#2-types-devenements-pris-en-charge)


## Utiliser les webhooks

Pour commencer à utiliser les webhooks avec Robaws, enregistrez votre endpoint webhook en effectuant un POST sur /api/v2/webhook-endpoints. Pour la définition complète de la requête, [consultez la documentation de référence de l'api](https://app.robaws.com/swagger-ui/index.html#/Webhooks/listEndpoints). Veuillez conserver le secret que nous vous renvoyons lors de la création de l'endpoint, car vous en aurez besoin pour vérifier nos signatures.

Après quelques secondes, lorsque votre abonnement devient actif, vous devriez recevoir de notre part des appels HTTP POST vers l'URL que vous avez spécifiée. 

Voici un exemple d'un tel 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": {
        ....
    }
}
```

## Vérifier la signature

Il est important que vous vérifiiez la signature que nous envoyons dans l'en-tête 'Robaws-Signature', car sinon vous ne pouvez pas être certain que l'appel HTTP provient bien de Robaws. Ceci est d'autant plus important que nous n'envoyons pas seulement l'id dans l'événement, mais l'ensemble des données.

Afin de vérifier notre signature, vous avez besoin du secret que nous avons renvoyé lors de la création de l'endpoint.

###### Étape 1 : extraire le timestamp et la signature de l'en-tête

Divisez l'en-tête, en utilisant le caractère , comme séparateur, pour obtenir une liste d'éléments. Divisez ensuite chaque élément, en utilisant le caractère = comme séparateur, pour obtenir une paire préfixe et valeur.
La valeur du préfixe t correspond au timestamp, et v1 correspond à la signature. Vous pouvez ignorer tous les autres éléments.
Si vous les divisez à nouveau sur "=", cela vous donne les valeurs dont vous avez besoin.

###### Étape 2 : préparer la chaîne signed_payload

La chaîne signed_payload est créée en concaténant :

Le timestamp (sous forme de chaîne)
Le caractère .
Le payload JSON réel (c'est-à-dire le corps de la requête)

###### Étape 3 : Déterminer la signature attendue

Calculez un HMAC avec la fonction de hachage SHA256. Utilisez le secret de signature de l'endpoint comme clé, et utilisez la chaîne signed_payload comme message. Convertissez le résultat en représentation hexadécimale.

###### Étape 4 : Comparer les signatures

Comparez la signature de l'en-tête à la signature attendue. Pour une correspondance d'égalité, calculez la différence entre le timestamp actuel et le timestamp reçu, puis décidez si la différence est dans votre tolérance pour vous protéger contre les attaques par rejeu. Pour vous protéger contre les attaques temporelles, utilisez une comparaison de chaînes à temps constant pour comparer la signature attendue à chacune des signatures reçues.

## Quelques considérations

* Seuls les utilisateurs admin peuvent enregistrer des endpoints. Actuellement, il n'y a pas d'interface pour enregistrer les endpoints webhook. Cela ne peut se faire que via l'API.
* Nous considérons le webhook comme réussi lorsque l'endpoint renvoie une réponse 2XX. Nous réessaierons plusieurs fois tant que votre endpoint ne parvient pas à répondre avec succès. Notre délai d'expiration de connexion est de 2 secondes et le délai d'expiration de lecture est de 2 secondes. Cela signifie que si nous ne recevons pas de réponse dans les 2 secondes, nous continuerons à réessayer la requête jusqu'à ce que nous en recevions une. Si nous n'obtenons jamais de réponse réussie, nous pouvons suspendre votre webhook sans avertissement.
* Les webhooks peuvent être testés facilement en utilisant https://webhook.site


## Types d'événements pris en charge

Actuellement, les types d'événements suivants sont pris en charge. Si vous avez besoin d'un autre événement, veuillez nous le faire savoir 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