Accepting callbacks

A callback lets you receive message delivery updates and/or inbound SMS from Notify to a URL you choose.

On a server you control, you should set up an endpoint that can accept POST requests. Notify will POST messages in a JSON format to the endpoint you specify.

To ensure that callbacks are coming from Notify and not some other malicious source, you will need to create a "bearer token" when setting up the callback URL. A bearer token should be a long randomised piece of text that an attacker wouldn’t be able to impersonate.

When creating a bearer token, you should:

  • keep your bearer token secure
  • change it if you have any reason to think it might no longer be trusted
  • make sure that callbacks you receive from Notify contain your bearer token in the Authorization header
  • use a hashed value so that Notify doesn’t hold the true token

Contents

Message delivery updates

When you send an email or text message through Notify, we can send a receipt to your callback URL to tell you if we were able to deliver it or not.

The JSON message that Notify sends has this format:

{
    "id": "UUID",
    "reference": "12345678",
    "to": "person@example.com",
    "status": "delivered",
    "notification_type": "email",
    "created_at": "2017-05-14T12:15:30.000000Z",
    "completed_at": "2017-05-14T12:15:30.000000Z",
    "sent_at": "2017-05-14T12:15:30.000000Z"
}

Fields

id
UUID
Notify’s ID for this notification. You can use this to correlate with the ID that is returned when you send a message.
reference
Optional string
The reference potentially sent with your API request
to
string

The email address or phone number of the recipient.

If notification_type is email, this is the recipient’s email address.

If notification_type is sms, this is the recipient’s E.164 formatted phone number.

status
string

The status of the notification.

Possible values:

  • sending
  • delivered
  • permanent-failure
  • temporary-failure
  • technical-failure
notification_type
string

The notification type, either email or sms

created_at
ISO-8601 string
The time in UTC that the service sent the request
completed_at
ISO-8601 string
The last time in UTC that the status was updated
sent_at
Optional ISO-8601 string
The time in UTC that the notification was sent

A simple callback handler might look like this:

Select language

Inbound SMS messages

If your service receives text messages in Notify, we can forward them to your callback URL as soon as they arrive.

The JSON message that Notify sends has this format:

{
    "id": "UUID",
    "source_number": "+61412987654",
    "destination_number": "+61412345678",
    "message": "Hello Notify!",
    "date_received": "2017-05-14T12:15:30.000000Z"
}

Fields

id
UUID
Notify’s ID for the message
source_number
string
The E.164 formatted phone number the message was sent from (the original recipient’s number)
destination_number
string
The E.164 formatted phone number the message was sent to (your service’s number)
message
string
The content of the received message
date_received
ISO-8601 string
The UTC datetime that the message was received by Notify

A simple callback handler might look like this:

Select language