Create a webhook endpoint

POST /v1/webhooks

Adds a webhook endpoint that Soosh sends events to, signed with a new secret.

Needs webhooks:write.

Over the API the secret is returned only here and when you rotate it, so store it now. People who can edit webhooks can also see it in the app.

Message statuses and new contacts

curl -X POST https://app.soosh.io/v1/webhooks \
  -H "Authorization: Bearer $SOOSH_API_KEY" \
  -H "Idempotency-Key: create-webhook-message-statuses-and-1" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/soosh",
    "description": "Order updates",
    "events": [
      "message.status",
      "contact.created"
    ],
    "headers": {
      "X-Api-Token": "your-own-token"
    }
  }'

const res = await fetch('https://app.soosh.io/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SOOSH_API_KEY}`,
    'Idempotency-Key': 'create-webhook-message-statuses-and-1',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://hooks.example.com/soosh",
    "description": "Order updates",
    "events": [
      "message.status",
      "contact.created"
    ],
    "headers": {
      "X-Api-Token": "your-own-token"
    }
  }),
});
console.log(await res.json());

import os
import requests

res = requests.post(
    "https://app.soosh.io/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['SOOSH_API_KEY']}", "Idempotency-Key": "create-webhook-message-statuses-and-1"},
    json={
        "url": "https://hooks.example.com/soosh",
        "description": "Order updates",
        "events": [
            "message.status",
            "contact.created",
        ],
        "headers": {
            "X-Api-Token": "your-own-token",
        },
    },
)
print(res.json())

Response201

{
  "id": "4c6e8a0c-2e4b-4d6f-b8a0-1c3e5a7c9e4b",
  "url": "https://hooks.example.com/soosh",
  "description": "Order updates",
  "events": [
    "message.status",
    "contact.created"
  ],
  "headers": {
    "X-Api-Token": "********"
  },
  "status": "active",
  "disabled_reason": null,
  "paused_until": null,
  "previous_secret_expires_at": null,
  "created_at": "2026-10-14T09:20:05.631Z",
  "updated_at": "2026-10-14T09:20:05.631Z",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSwQ3x7Vn5hT0c="
}

Body

url string Required

An https:// URL on the internet. It can’t have a username or password, or point to an internal or private address.

events array of strings Required

Any of message.received message.sent message.status contact.created contact.updated contact.deleted template.status chat.assigned chat.closed chat.reopened broadcast.status. At least 1 item.

description string

A note to tell your endpoints apart.

Up to 500 characters.

headers object

Custom headers sent with every request. You can set at most 10. Names are 1 to 64 letters, digits or hyphens. Values are up to 1024 characters, with no line breaks. The API returns every value as ********.

A map; each value is a string.

Headers

Idempotency-Key string

Send one so a retry doesn’t create the endpoint twice. See Retrying safely.

1 to 255 characters.

Choosing the events

A key needs the read scope of every event the endpoint subscribes to: messages:read for message.*, contacts:read for contact.*, templates:read for template.* and broadcasts:read for broadcast.*. The API has no read-only chat scope, so chat.* events need chats:write.

Every event is listed in Webhook events.

Headers you can't set

Host, Content-Length, Content-Type, Content-Encoding, Transfer-Encoding, TE, Trailer, Connection, Keep-Alive, Upgrade, Expect, User-Agent, Proxy-* and Webhook-*.

After you create it

Check each request’s signature with the secret. See Verify webhooks.

Returns

201 The endpoint, with its secret.

id string · uuid

url string

Where Soosh sends the events.

description string

Up to 500 characters.

events array of strings

Any of message.received message.sent message.status contact.created contact.updated contact.deleted template.status chat.assigned chat.closed chat.reopened broadcast.status.

headers object

Custom headers sent with every request, by name. Values are never returned: each reads ********.

A map; each value is a string. Up to 10 keys.

status string

active; paused while the endpoint keeps failing (Soosh tries again by itself at paused_until, and events wait meanwhile); or disabled when it’s turned off.

disabled_reason string · nullable

Why Soosh turned the endpoint off: failing after a day of nothing but failures; no_secret when it has no signing secret (nothing is ever sent unsigned: rotate the secret, then turn it back on). An endpoint a key created belongs to that key, and moves to its replacement when the key is rotated; it is turned off when the key is revoked (key_revoked), expires without a replacement (key_expired), or loses webhooks:write or the read scope of an event it sends (key_scopes). null otherwise, including when a person turned it off. Turn it back on with enabled: true; deliveries that were waiting are still sent if you do within a day of it being turned off.

paused_until string · date-time · nullable

When a paused endpoint is tried again; null unless status is paused.

previous_secret_expires_at string · date-time · nullable

During a rotation, when the old secret stops signing; null otherwise.

created_at string · date-time

updated_at string · date-time

secret string

The signing secret (whsec_ and base64), shown this once. The HMAC key is the base64-decoded part after whsec_.

Errors

Besides the ones every request can get:

403scope_missingThe key lacks the read scope of an event the endpoint subscribes to. error.details.scope says which.

403feature_not_in_planAn event isn’t on your plan.

422limit_reachedThe workspace already has its webhook_endpoints limit.

422invalid_fieldThe url, a header or the events break a rule: for example an http:// URL, a private address, more than 10 headers or an unknown event.

409idempotency_in_progressA request with the same Idempotency-Key is still running.

422idempotency_mismatchThe Idempotency-Key was used before for a different request, or by another of your API keys.