Webhooks¶
A webhook is a callback mechanism that allows you to be notified when an action occurs within the Care Messenger API. This callback is implemented by specifiying a URL where you would like to receive notifications via a HTTP POST.
Webhooks can be created using the following API endpoint.
https://api.caremessenger.co.uk/v2/webhook
Event Types¶
When creating a webhook, an event type is be specified to designate the type of events you would like to receive at the the URL you provide. The currently supported event types and their associated events can be seen below.
Type |
Event Name |
Description |
|---|---|---|
messages |
message_read |
Sent when a single recipient responds to a given message set |
presence |
online |
Sent when a user comes online |
Only sent for CustomerAdmin and Resident accounts |
||
presence |
offline |
Sent when a user goes offline |
Only sent for CustomerAdmin and Resident accounts |
Registering a Webhook¶
To register a webhook, sent a HTTP POST request to the webhook resource with a body containing the following fields.
- customer
The id of the object that will own the webhook.
- type
The type of events to receive via this webhook, one of either
messagesoradmin- active
Should the webhook be active
- url
The URL at which you would like to receive notifications via HTTP POST
Example Request¶
Sent HTTP POST request to
https://api.caremessenger.co.uk/v2/webhook
Containing a body such as
{
"customer": 2,
"type": "messages",
"active": true,
"url": "https://acmecorp.com/message-events/"
}
Example Response¶
If successful, a 201 CREATED response will be received with a body similar to the below
{
"id": 6,
"customer": 18,
"type": "admin",
"created": "2015-03-24T23:30:10.490467Z",
"active": true,
"url": "https://acmecorp.com/message-events/"
}
Events, Responses and Retries¶
Once a webhook is in place, when an event occurs a HTTP POST will be made to the URL specified in the webhook. If your server successfully receives this POST, it should respond with a 200 or 201 response code. If you do not respond the webhook will be retried with exponential backoff for the next 5 minutes.
If no respone has been received within that period, retries will be stopped. Currently no further escalation will occur.
Webhook POST¶
When a POST is made to a registered webhook, it will contain the following fields
- customer
The customer for whom the event occured
- timestamp
Timestamp for the event occurrence
- event_name
The name of the event that occurred
- site
The site at which the event occurred
- data
A JSON data blob relevant to the event that just occurred.
Example Webhook POST¶
An example of what might be received when an event occurs can be seen below. This example relates to a message_read event.
{
"customer": 2,
"timestamp": "2014-06-30T10:04:40.938Z",
"event_name": "message_read",
"site": 17,
"data": {
"status": "read",
"responses": [
{
"message": 70,
"message_recipient": 135,
"id": 32,
"choice": {
"next_step": null,
"message": 70,
"id": 75,
"choice_text": "Choice 1"
}
}
],
"message_set": {
"message_recipient_id": null,
"ingress_type": "web",
"cli": "",
"created": "2014-06-30T10:03:49.632Z",
"messages": [
{
"body": "This is the body of sample message 1",
"videos": [],
"choices": [
{
"next_step": null,
"message": 70,
"id": 81,
"choice_text": "Choice 1"
},
{
"next_step": null,
"message": 70,
"id": 82,
"choice_text": "Choice 2"
},
{
"next_step": null,
"message": 70,
"id": 83,
"choice_text": "Choice 3"
}
],
"body_type": "text",
"images": [],
"id": 70,
"subject": "Sample Message 1"
},
{
"body": "This is the body of sample message 2",
"videos": [],
"choices": [
{
"next_step": null,
"message": 71,
"id": 84,
"choice_text": "Choice 1"
},
{
"next_step": null,
"message": 71,
"id": 85,
"choice_text": "Choice 2"
},
{
"next_step": null,
"message": 71,
"id": 86,
"choice_text": "Choice 3"
}
],
"body_type": "text",
"images": [],
"id": 71,
"subject": "Sample Message 1"
}
],
"site": 17,
"system_message_type": "",
"theme": "default",
"message_type": "standard",
"id": 59,
"sender": {
"username": "roger",
"first_name": "Roger",
"last_name": "Boardman",
"locale": "en_GB",
"avatar_original": "http://localhost:8000/media/users/avatars/b8b9e934e9598097b6635e73d41c6925_1.png",
"is_active": true,
"user_type": "staff",
"slug": "roger",
"time_zone": "Europe/London",
"avatar_large": "http://localhost:8000/media/CACHE/images/users/avatars/b8b9e934e9598097b6635e73d41c6925_1/6ca401b707666ea3d0f31886af0d9c94.jpg",
"avatar": "users/avatars/b8b9e934e9598097b6635e73d41c6925_1.png",
"id": 2,
"avatar_thumb": "http://localhost:8000/media/CACHE/images/users/avatars/b8b9e934e9598097b6635e73d41c6925_1/2d3c88d905fe1bf3bda9702d759ef376.jpg",
"email": "roger@bxthree.com",
"date_joined": "2013-11-07T16:44:58.806Z"
}
},
"status_changed": "2014-06-30T10:04:40.902Z",
"recipient": {
"username": "tester",
"customer": 2,
"slug": "tester",
"last_name": "Tester",
"user_type": "resident",
"gender": "male",
"hardware_id": "00:15:85:00:00:FF",
"is_active": true,
"site": 3,
"id": 35,
"locale": "en_GB",
"time_zone": "Europe/London",
"avatar_large": "http://localhost:8000/media/CACHE/images/users/avatars/jayrobinson_128_2/34631ede2b49d3dad0184973f1e413bd.jpg",
"avatar": "users/avatars/jayrobinson_128_2.jpg",
"avatar_original": "http://localhost:8000/media/users/avatars/jayrobinson_128_2.jpg",
"first_name": "Resident",
"avatar_thumb": "http://localhost:8000/media/CACHE/images/users/avatars/jayrobinson_128_2/7581e89c8094f3384ef19a3d7cc5caae.jpg",
"email": "tester@resident.com",
"date_joined": "2013-11-11T21:50:05Z"
},
"id": 46
}
}