Webhooks are a mechanism that allows your application to receive real-time data or event-driven updates from our service without the need to continuously poll for new information. Essentially, webhooks are user-defined HTTP callbacks that are triggered by specific events in the service you're integrating with. When such an event occurs, the service makes an HTTP request (always POST) to the webhook URL you have configured, delivering the relevant data as payload.
Our goal with the introduction of webhooks is to remove the need for you to poll the api for updates using the since endpoints and help get a more accurate picture of what's happening on your system.
Feedback
The number of event types is currently limited while we verify the operation of our underlying infrastructure. We'll be implementing more and increasing coverage over the next few releases. Should there be something specific you want an event for then raise it on the user community under API feature suggestions.
Webhook Id
To allow you to use a single endpoint for all events we provide a header value under x-webhook-id that will match the id provided when you created the webhook. You can then change your behaviour depending on the subscription recieved to save creating multiple recipient endpoints for each event.
Webhook Environment
To avoid confusion about where payloads are coming from, we've included the environment in all webhook payloads that aren't from your production environment. This property will be completely omitted from production payloads, so ensure your method of parsing allows them to be ignored.
- Production, no enviroment information included.
- Test, this is indicated via a
Stagingenvironment being shown. - Internal Rubixx Environments, these can be identified via
DevelopmentorQAbeing seen in the payload.
Payload Examples
The result payload will be the same as the since endpoint for the entity related to the event with some information related to the event. The only time this isn't the case is when we no longer have the data required to display those payloads such as a person's contact details being deleted, here we'd just provide the id of the entity that was deleted. Below are some examples to showcase what we mean by this, keep in mind these might not match the current state 100%. We recommend checking the get endpoints for up to date payload examples for the "data" section.
{
"eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"eventType": "ArrearsStageHistoryCreated",
"when": "2024-10-03T09:53:36.1115018Z",
"data": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"stage": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "string"
},
"balanceAtStart": 0,
"startDate": "2024-10-03T09:56:57.144Z",
"endDate": "2024-10-03T09:56:57.144Z",
"owner": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "string"
},
"isManual": true,
"createdDate": "2024-10-03T09:56:57.144Z",
"updatedDate": "2024-10-03T09:56:57.144Z"
}
}
{
"eventId": "a8a71cd2-c4c2-4dd4-aa0c-d94e8563f109",
"eventType": "CaseCreated",
"when": "2024-10-02T14:50:38.2610575Z",
"data": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"reference": "string",
"description": "string",
"type": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "string"
},
"subType": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "string"
},
"priority": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "string"
},
"status": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "string"
},
"source": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "string"
},
"owner": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "string"
},
"loggedDate": "2024-10-03T09:56:57.144Z",
"reportedDate": "2024-10-03T09:56:57.144Z",
"targetDate": "2024-10-03T09:56:57.144Z",
"cancelledDate": "2024-10-03T09:56:57.144Z",
"closedDate": "2024-10-03T09:56:57.144Z",
"closeReason": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "string"
},
"slippageReason": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "string"
},
"createdDate": "2024-10-03T09:56:57.144Z",
"updatedDate": "2024-10-03T09:56:57.144Z"
}
}
{
"eventId": "3b6d1914-2bc5-42aa-a2a6-9272e52a178f",
"eventType": "TaskCreated",
"when": "2024-10-02T14:32:47.4393703Z",
"data": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"relatedId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"parentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"text": "string",
"raisedBy": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "string"
},
"raisedDate": "2024-10-03T09:56:57.144Z",
"isSystemEvent": true,
"hasChildren": true,
"createdDate": "2024-10-03T09:56:57.144Z",
"updatedDate": "2024-10-03T09:56:57.144Z"
}
}
{
"eventId": "1ba699e4-305a-475f-afaf-e29f390379aa",
"eventType": "PersonContactDetailDeleted",
"when": "2024-10-03T10:55:45.261025Z",
"data": {
"entityId": "56e5d6b4-9500-4524-564a-08dcd6fd13dc"
}
}
Validating Payloads
We implement HMAC (Hash-based Message Authentication Code) for you to validate payloads recieved by your endpoint are coming from us. When sending a webhook, we generate a cryptographic hash (signature) using a combination of the payload and a shared secret key, known only by our server and you. This signature is included in the request header x-hmac-signature. You can then use the same secret key shared on webhook creation to compute your own hash of the received payload and compare it with the provided signature. If the signatures match, it ensures that the data was sent by us and has not been tampered with in transit.
Webhook Suspension
From 2024.6 onwards we've implemented a system that will detect when an unexpectedly high volume of error responses are received when we attempt to call your configured endpoints. This system will automatically disable the subscription and inform you via an email configured against the subscriptions. You're able to reactivate the subscription yourself but if it continues to error it will automatically deactivate again.