.. webhooks.rst: 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. .. sourcecode:: shell 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 ``messages`` or ``admin`` `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 .. sourcecode:: shell https://api.caremessenger.co.uk/v2/webhook Containing a body such as .. sourcecode:: javascript { "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 .. sourcecode:: javascript { "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. .. sourcecode:: javascript { "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 } }