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 recieve from Notify contain your bearer token as an authorisation 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
status
string

The status of the notification

Possible values:

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

The notification type, 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

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": "0412345678",
    "message": "Hello Notify!",
    "date_received": "2017-05-14T12:15:30.000000Z"
}

Fields

id
UUID
Notify’s ID for the status receipts
source_number
string
The phone number the message was sent from
destination_number
string
The number the message was sent to (your number)
message
string
The received message
date_received
ISO-8601 string
The UTC datetime that the message was received by Notify