Skip to content

Webhooks: notifications to your system

Updated:

On this page

A webhook works like a text message with a notification, only sent to your program instead of a person. When something happens in SMS Portal|app, our server sends a short message with data to the address you give. Your program can then, for example, save a customer’s reply in its own database.

Add a webhook

  1. In the dashboard menu click “Webhooks”.
  2. Click “Create Webhook”.
  3. In “Name (optional)” type a short name, for example “Production CRM”. It helps you tell webhooks apart.
  4. In “Delivery URL” enter an address in your system. The server sends POST requests there.
  5. In “Signing Secret” type your own string or click “Generate”. The secret lets you check that the data really comes from us.
  6. In “Events” tick at least one: MESSAGE_RECEIVED (SMS received), MESSAGE_SENT (sent), MESSAGE_DELIVERED (delivered) or MESSAGE_FAILED (did not go out).
  7. Click “Create”.
The create webhook window with the delivery URL, signing secret and the list of events
The create webhook window with the delivery URL, signing secret and the list of events

On the webhook card you can switch it off and on, edit it, copy the URL, and show or copy the secret. You can have up to 5 webhooks.

What your system receives

Each notification is a POST request with data in JSON format and an X-Signature header. The data includes, among other things, the message ID, the number, the text, the device ID and the event name in the webhookEvent field. Samples of every event are at the bottom of the Webhooks page, in “Security & Implementation Guide”.

Your system should:

  1. Accept the POST request.
  2. Answer with a 2XX code, for example 200.
  3. Do it within 10 seconds.

Check the signature

The X-Signature header is a signature calculated with HMAC-SHA256 from the data and your secret. Calculate it on your side and compare. If it does not match, reject the request. Ready examples in Node.js and Python are in the “Verification” tab on the Webhooks page.

Delivery log and retries

Click the “Deliveries” tab. You see every notification with the columns “Event”, “Device”, “Status”, “Delivery Url” and “Created At”. Clicking the eye icon opens the data that went to your system. Filters narrow the list by phone, webhook, event type, status and date.

StatusWhat it means
DeliveredYour system answered correctly.
PendingThe notification waits for its first attempt.
RetryingAn attempt failed and the server will try again.
FailedThe server stopped trying.

When your system does not answer correctly, we resend after: 3 minutes, 5 minutes, 30 minutes, 1 hour, 6 hours, 1 day, 3 days, 7 days and 30 days. A notification gets at most 10 attempts. For client errors (4XX codes) the server stops after the third attempt. A switched-off webhook no longer gets notifications.

Questions and answers

How many webhooks can I have?
Up to 5 per account. When you reach the limit, delete one to add another.
What if my system does not answer?
SMS Portal|app tries again after 3 minutes, then after 5 and 30 minutes, 1 hour and later, up to 10 attempts in total.

Didn’t find the answer? Contact us

Send your first SMS today

Create a free account, connect your phone and see how customers respond to messages from your number.