Skip to content

SmsAddWebhook

POST sms/webhook

Creates a public callback URL for a provider profile. This is how a profile with deliveryUpdateBy: "WEBHOOK" receives delivery reports: the provider posts events to the URL returned here.

The URL contains a generated uuid, so it is unguessable, and the secretKey is what proves an event really came from the provider. Both matter: the endpoint is public by necessity — an operator cannot carry a manager JWT.

Access Control

Allowed role: admin, within the brand of the caller.

Request

POST https://{broker_domain}/sms/webhook
{
  "name": "Twilio status callbacks",
  "profileId": 3,
  "status": "ENABLED",
  "secretKeyAutoGenerate": true
}

{
  "command": "SmsAddWebhook",
  "extID": "1",
  "data": {
    "name": "Twilio status callbacks",
    "profileId": 3,
    "status": "ENABLED",
    "secretKeyAutoGenerate": true
  }
}

const res = await platform.SmsAddWebhook({
  name: "Twilio status callbacks",
  profileId: 3,
  status: "ENABLED",
  secretKeyAutoGenerate: true
});

Request Data

Field Type Required Description
name string Yes Webhook name for the UI
description string No Free-form note
profileId int Yes Provider profile the reports belong to
status enum Yes ENABLED or DISABLED
secretKey string No Signing secret, 10..255 characters. Use the provider value when the provider issues it
secretKeyAutoGenerate bool No Generate the secret instead of passing one
events array No Event names to accept. Empty means every event the adapter understands

Behavior

  • The full public URL is composed by the integration domain: the module returns the path, because only the deployment knows the host.
  • The uuid is stable for the lifetime of the webhook — it is configured on the provider side, so regenerating it would silently stop delivery reports.
  • Put the returned path into the provider dashboard field for delivery callbacks; the adapter page lists which field that is.

Response Data

A webhook can be created for any profile of the brand — the mode is checked when an event arrives. A profile that is not in WEBHOOK mode answers incoming events with PROFILE_NOT_IN_WEBHOOK_MODE.

{
  "id": 2,
  "brand": "default",
  "profileId": 3,
  "uuid": "9f2a1c7d4b6e",
  "name": "Twilio status callbacks",
  "description": null,
  "secretKey": "s3cr3t-generated-value",
  "events": [],
  "status": "ENABLED",
  "path": "/sms/handleWebhooks/9f2a1c7d4b6e",
  "createdAt": "2026-08-24 13:55:20"
}

Errors

Code Error Description
400 VALIDATION_ERROR Secret is shorter than 10 characters, or a required field is missing
400 PROVIDER_IS_DISABLED The provider behind the profile is disabled
404 PROFILE_NOT_FOUND Profile not found in the brand
404 PROVIDER_NOT_FOUND The profile points at a provider that no longer exists