Skip to content
Docs
Open Soosh
View as Markdown
How-to guideIntegrations

Set up a webhook

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

5 minutesDevelopersUpdated

Before you start

Section titled “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

Section titled “Add the webhook”

  1. Go to 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.

    Open in Soosh

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

Section titled “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.

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

Section titled “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.

Section titled “Related”