Webhooks

A webhook enables you to receive notifications for message delivery status, allowing you to track the status of your campaign in real time. To receive notifications on SMS messages via Webhooks, you can create a webhook project here.

Set up endpoints/customer specific URL

A webhook endpoint receives requests from Interact, notifying you about events related to your SMS campaign such as messages submitted, failed, and delivered. Enter the URL of your domain that would receive the requests from Interact in "Webhook endpoint URL".

Verify webhook endpoint

Click "Verify" to receive a secret to the endpoint URL mentioned above. The webhook endpoint must return a 200 OK response with the secret in response body to successfully verify and create the webhook.

Signature

Additionally, you can verify the authenticity of requests from Webex Interact with an optional signature of your choice.

Choose Topics

While configuring a webhook, use the Topics section to choose which events you want to receive.

For example, if you subscribe to the delivered event, you'll receive a webhook every time a message is successfully delivered to a customer.

Sample webhook event responses

//Sample response for a message submitted to operator
{
  "specversion": "1.0",
  "type": "com.reach.messages.sms.status",
  "source": "https://api.reach.com/messages/sms",
  "time": 1740980460557,
  "datacontenttype": "application/json",
  "data": {
    "status": "submitted",
    "channel": "sms",
    "code": "1003"
  }
}

//Sample response for a succesfully delivered message
{
   "specversion":"1.0",
   "type":"com.reach.messages.sms.status",
   "source":"https://api.reach.com/messages/sms",
   "time": 1740980460557,
   "datacontenttype":"application/json",
   "data":{
      "status":"delivered",
      "channel":"sms",
      "phone":"+44771782XXXX",
      "correlationid":"cid_2rR8xzxxedfTt",
   }
}

//Sample response for a failed message
{
   "specversion":"1.0",
   "type":"com.reach.messages.sms.status",
   "source":"https://api.reach.com/messages/sms",
   "time": 1740980460557,
   "datacontenttype":"application/json",
   "data":{
      "status":"failed",
      "channel":"sms",
      "phone":"+44786000XXXX",
      "correlationid":"cid_2qQI8vLzxesdfTlxx",
   }
}

//Sample response when a user clicks on a shortlink in the sent SMS
{
   "specversion":"1.0",
   "type":"com.reach.messages.sms.status",
   "source":"https://api.reach.com/messages/sms",
   "time": 1740980460557,
   "datacontenttype":"application/json",
   "data":{
      "status":"clicked",
      "channel":"sms",
      "correlationid":"cid_2qQI8vLzxesdfTlxx",
   }
}

//Sample response when a user replies to your number
{
   "specversion":"1.0",
   "type":"com.reach.messages.sms.status",
   "source":"https://api.reach.com/messages/sms",
   "time": 1740980460557,
   "datacontenttype":"application/json",
   "data":{
      "status":"new",
      "channel":"sms",
      "message":"INBOUND MESSAGE",
      "phone_number":"+447860009XXX"
   }
}

Webhook parameters

Parameter	Description
type	Specifies the event type such as SMS message status update.
source	Indicates the event's origin, such as the API URL..
time	Timestamp (Unix epoch milliseconds) of the event.
datacontenttype	Specifies the data format, typically "application/json".
→ status	SMS message status (submitted, delivered, failed, clicked).
→ channel	Specifies channel used to send the message
→ code	Status code providing information about the message state.
→ phone	(For Delivered and Failed events) Specifies the recipient’s phone number.
→ correlationid	A unique identifier assigned to each request for tracking and reference. It is included in API requests.
→ message	(For inbound message event) Specifies the incoming message content