Overview

This page lists examples of the payloads that will be sent to registered transactional SMS webhooks. The webhook payloads may differ based on the event that triggered it, or whether certain settings have been enabled.

The webhook event types are split into 2 categories

Transaction Events

  • Sent
  • Failed
  • Bounce

Recipient Events

  • Delivered
  • Reply

Responses

Generic Webhook Payload

{
  "id": "e0fce57e-1064-4cb4-9b76-8aa8bf4b0678",
  "type": "reply",
  "timestamp": "2023-09-07T18:45:31+02:00",
  "data": {
    "transaction": {
      "id": 5,
      "custom_id": "",
      "campaign": {
        "name": "Different Campaign"
      },
      "sent_timestamp": "2023-08-01T19:06:15+02:00",
      "recipient": {
        "mobile_number": "27792899967"
      }
    }
  }
}

Special Webhook Payloads

Reply event payload

These payloads will include an extra field in the data element, with the key reply
{
  "id": "e0fce57e-1064-4cb4-9b76-8aa8bf4b0678",
  "type": "reply",
  "timestamp": "2023-09-07T18:45:31+02:00",
  "data": {
    "transaction": {
      "id": 5,
      "custom_id": "",
      "campaign": {
        "name": "Different Campaign"
      },
      "sent_timestamp": "2023-08-01T19:06:15+02:00",
      "recipient": {
        "mobile_number": "27792899967"
      }
    },
    "reply": {
      "content": "STOP",
      "received_timestamp": "2022-05-24T10:28:58+02:00"
    }
  }
}

Bounce event payload

These payloads will include an extra field in the data element, with the key bounce
{
  "id": "e0fce57e-1064-4cb4-9b76-8aa8bf4b0678",
  "type": "bounce",
  "timestamp": "2023-09-08T11:43:26+02:00",
  "data": {
    "transaction": {
      "id": 5,
      "custom_id": "",
      "campaign": {
        "name": "Different Campaign"
      },
      "sent_timestamp": "2023-08-01T19:06:15+02:00",
      "recipient": {
        "mobile_number": "27792899967"
      }
    },
    "bounce": {
      "message": "policy-related",
      "type": "soft",
      "received_timestamp": "2010-08-02T14:55:16+02:00"
    }
  }
}

Properties

Generic Payload Properties

Property

Sub-Property

Description

Data Type

 Parameters

id

This is the UUID (Universally Unique IDentifier), of the webhook that the event data was passed to, to get this result

String

type

This is the type of event that was returned through the webhook

String

  • Sent

  • Failed

  • Bounce

  • Delivered

  • Reply

timestamp

This is the date and time of when the webhook payload was processed in an Iso8601 format

(Ie. yyyy-MM-dd'T'HH:mm:ss[+|-]Z)

DateTime

data

This is the generic data that gets passed for every event returned through the webhook

 Array

data

transaction

This element contains information about the original transactional SMS that the even was generated from, such as it’s ID, Custom ID (if applicable) and the name of any campaign(s) that it may be assigned to.

Array
data->transaction

id

This is the ID of the originating Transactional SMS

Int

data->transaction

 campaign

This is the information of a campaign that has been assigned to the transactional SMS

Array

data->transaction

 sent_timestamp

This is the date that the original transactional message was sent to the recipient in Iso8601 format

(Ie. yyyy-MM-dd'T'HH:mm:ss[+|-]Z)

 DateTime

data->transaction

 recipient

This is an array of information about the recipient that was sent the transactional message

 Array

Reply Payload Properties

Property

Sub-Property

Description

Data Type

data

 reply

This is an array of data that contains information related to the reply event

 Array

data->reply

 content

This is the text content that was in the recipients reply to the originating transactional message

String

data->reply

 received_timestamp

This is the datetime of when the reply was received on the system in the Iso8601 format

(Ie. yyyy-MM-dd'T'HH:mm:ss[+|-]Z)

 DateTime

Bounce Payload Properties

Property

Sub-Property

Description

Data Type

 Parameters

data

 bounce

This is an array of data that contains information related to a bounce event

 Array

data->bounce

 message

This is a string of data with a reason why the bounce happened.

String

data->bounce

 type

This indicates whether the bounce with hard or soft.

 String

  • Hard

  • Soft

data->bounce

 received_timestamp

This is the datetime of when the bounce data was received on the system in the Iso8601 format

(Ie. yyyy-MM-dd'T'HH:mm:ss[+|-]Z)

 DateTime