# Set up a webhook

> Have Soosh tell your system the moment a message arrives, a contact is created or a chat is handed over.

Source: https://docs.soosh.io/guides/integrations/set-up-a-webhook/

## Before you start

- Owner or admin role in Soosh
- An address on your server that accepts a `POST` with a JSON body and answers with a `2xx` status

## Add the webhook

1. Go to [**Settings > Webhooks**](https://app.soosh.io/settings/webhooks) and click **Add webhook**.
2. In **Name**, enter what it's for, like *Order system*.
3. In **Webhook URL**, enter your address.
4. Under **Events**, tick what to hear about: **Message Incoming**, **Message
   Sent**, **Message Outgoing**, **Contact Created**, **Transfer Created**,
   **Transfer Assigned**, **Transfer Resumed**.
5. Optional: in **Secret**, enter a secret to check that requests come from
   Soosh.
6. Click **Create**, then **Test webhook**.

   *Picture: The New webhook page with the name Order system, the URL, and Message Incoming and Contact Created ticked under Events*

The test sends an event called `test`. Soosh says **Test webhook sent
successfully**, or what went wrong, like your address answering with an error
or not answering within 15 seconds.

## Check the signature

With a secret set, every request has an `X-Webhook-Signature` header:
`sha256=` followed by the HMAC-SHA256 of the raw body, using your secret.
Compute the same on your side and compare before trusting the request.

```js
import crypto from 'node:crypto';

function fromSoosh(rawBody, header, secret) {
  const expected = Buffer.from('sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex'));
  const received = Buffer.from(String(header ?? ''));
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}
```

## Result

Soosh sends each event as it happens: a `POST` with `event`, `timestamp` and
`data`. If your address doesn't answer with a `2xx`, Soosh tries 3 times in
all, waiting a little longer each time.

## Related

- Reference: [Webhooks API](https://docs.soosh.io/reference/api/webhooks/)