Callbacks can automate the production of a delivery receipt or persist the status of a notification to your database.
A callback lets you receive messages about the state of notifications from GC Notify to a URL you choose. Callbacks are when GC Notify sends
POST requests to your system. You can get callbacks when an email or text message you’ve sent is delivered or fails.
You'll need to provide a
Bearer token, for security. We'll add this to the authorization header of the callback request.
# Set up callbacks
You must provide:
- a URL where Notify will post the callback to
Bearertoken, for security, which GC Notify will put in the authorization header of the requests
To do this:
- Sign in to GC Notify (opens new window).
- Go to the API integration page.
- Select Callbacks.
When creating a
Bearer token, you should:
- Keep your
- Change it if you have any reason to think it might no longer be trusted
- Make sure that callbacks you receive from GC Notify contain your bearer token in the
- Use a hashed value so that GC Notify doesn't hold the true token
# Message delivery receipts
When you send an email or text message, GC Notify will send a receipt to your callback URL to tell you if it was delivered or not. This is an automated method to get the status of messages.
This functionality works with test API keys, but does not work with smoke testing email addresses or phone numbers.
The callback message is formatted in JSON. All of the values are strings. The key, description and format of the callback message arguments will be:
| ||GC Notify’s id for the status receipts||UUID|
| ||The reference sent by the service||12345678|
| ||The email address or phone number of the firstname.lastname@example.org or 01234567890|
| ||The status of the notification|
| ||The detailed response from the provider. This will only be not null in a case of a technical failure|
| ||The time the service sent the request|
| ||The last time the status was updated|
| ||The time the notification was sent|
| ||The notification type|
Multiple callbacks for a notification
You might receive multiple callbacks for one sent notification. For example, the receiving mail server might accept the email (triggering a delivery notification), but after processing the email, the receiving mail server might determine that the email actually results in a bounce (triggering a bounce notification).
Callbacks are sent in the order they are received.