Skip to content

Get Webhook Calls

Context

A webhook is an efficient way to receive real-time notifications and data from external systems.

By configuring a URL in your system, you can allow other services to publish information to this URL whenever a relevant event occurs. This means that instead of constantly querying these systems for updates, the data arrives automatically as soon as it happens.

This approach is especially useful for automating processes and reacting instantly to important events, such as new transactions, order updates, or data changes, saving time and resources.

This documentation aims to clarify the behavior of our webhooks, facilitating integration and ensuring a faster and more efficient implementation process.

Standard Format of Webhook Messages

Messages sent by the webhook are solely intended to notify about record changes without providing full details of the change itself. This simplified model helps maintain secure and efficient communication via webhook.

After receiving a webhook notification, it is common for your system to perform an additional API query to get complete details of the modified record.

Each webhook message contains the following elements:

  • status: Indicates the type of change made to the object, such as CREATION, UPDATE, etc.
  • params: A dictionary containing the parameters necessary to identify the affected resource.
  • resource: The URI of the changed resource, which can be used to query the updated or created data.
  • tenant_id: The customer identifier to which the event refers.
  • topic: Defines the category or type of event, helping to classify the nature of the notification.

Example Message

{
  "data": {
    "status": "CREATION",
    "params": {
      "id": "debde69a-2dbb-427b-b478-6cffd7930ecf"
    },
    "resource": "/v0/tickets/debde69a-2dbb-427b-b478-6cffd7930ecf"
  },
  "tenant_id": "3b5cf468-c858-404b-9e53-630e3df9d74a",
  "topic": "sac_ticket"
}

Interpretation of Status in Webhook Messages

The status field indicates the operation performed on a record in the system and informs the webhook consumer of the action taken. Possible values are:

  • CREATION: Indicates a record creation operation in the specified topic.
  • UPDATE: Indicates an update to an existing record.
  • DELETION: Indicates the deletion of a record.

⚠️ If your system stores data from our APIs, it is essential to apply updates and deletions as indicated, as they may involve moderation and removal of sensitive customer information.

Subscription Topics and Notification Examples

When subscribing to receive notifications from our webhook, your URL will receive messages related to different topics, each tied to a specific resource. Below is the definition of each available topic, along with its possible statuses and a message example.

Topic Description Possible Statuses Message Example
sac_ticket Customer support ticket events CREATION, UPDATE, DELETION
{
  "data": {
    "status": "CREATION",
    "params": {
      "id": "debde69a-2dbb-427b-b478-6cffd7930ecf",
    },
    "resource": "/v0/tickets/debde69a-2dbb-427b-b478-6cffd7930ecf"
  },
  "tenant_id": "3b5cf468-c858-404b-9e53-630e3df9d74a",
  "topic": "sac_ticket"
}
sac_message Customer support ticket message events CREATION, UPDATE, DELETION
{ 
  "data": {
    "status": "CREATION",
    "params": {
      "ticket_id": "debde69a-2dbb-427b-b478-6cffd7930ecf",
      "id": "39697476-cbc3-4154-bf43-165464f66197",
    },
    "resource": "/v0/tickets/debde69a-2dbb-427b-b478-6cffd7930ecf/messages/39697476-cbc3-4154-bf43-165464f66197"
  },
  "tenant_id": "3b5cf468-c858-404b-9e53-630e3df9d74a",
  "topic": "sac_message"
}

Receive Webhook Updates

To configure a webhook, follow the documentation in the developers portal