Webhooks are a way for web applications to communicate with each other in real-time. They allow you to send data from one application to another as soon as an event occurs. This is useful for integrating different systems and automating processes. In the Darwin API, webhooks are used to send events to external systems when specific actions occur in the Darwin platform. For example, you can set up a webhook to receive a notification whenever a new session is opened or closed. This allows you to take immediate action based on these events. You can create, update, and remove webhooks using the Darwin API. This section provides endpoints for managing webhooks. When you create a webhook, you specify the URL of the external system that will receive the events and the types of events you want to be notified about. You can use wildcards to match multiple events. For example, you can set up a webhook to receive notifications for all session events or all function call events. Here are all events that you can subscribe to:
session.opened: Notification received when a new session is created. A new session occurs when a conversation begins with a new WhatsApp number or when a previously closed conversation is considered as new.
session.closed: Occurs when the conversation is closed due to client inactivity, typically set to 7 days by default but can be modified.
session.closed.unforwarded: Occurs when a session is closed but not forwarded.
session.forwarded: Notification received when a session is rated or escalated because the conversation is requested to be transferred.
session.forwarded.qualified: Notification received when a session is forwarded as qualified.
session.forwarded.escalated: Notification received when a session is forwarded as escalated.
session.forwarded.recovered: Notification received when a session is forwarded as recovered.
session.analyzed: Triggered once smart fields are calculated, and the conversation summary is generated.
session.stage.transitioned: Notification received when a session transitions between pipeline stages.
session.*: Wildcard to subscribe to all session events.
function.call.: Notification received when a function call is made. You can replace
<functionName>with the name of the function you want to be notified about.function.call.*: Wildcard to subscribe to all function call events.
function.*: Wildcard to subscribe to all function events.
All webhooks are authenticated using a secret key that is generated when the webhook is created. This secret key is used to sign the payload of the event, ensuring that the event is sent by Darwin and not tampered with during transit. When you create a webhook, you will receive the secret key, which you should keep secure and use to verify the authenticity of the events you receive. This secret will be used to generate the X-SIGNATURE header when you receive an event from Darwin. You can verify the signature using the same method as generating it, here is an example of how to do that:
const crypto = require('crypto'); const payload = JSON.stringify(request.body); const expectedSignature = crypto.createHmac('sha256', 'your_app_secret') .update(payload) .digest('hex'); if (receivedSignature !== expectedSignature) { throw new Error('Invalid signature'); }All webhooks have the following properties:
eventType: The type of event that the webhook is subscribed to. This can be one of the events listed above.
timestamp: The timestamp when the event occurred.
agentId: The ID of the agent that the event is related to.
agentName: The name of the agent that the event is related to.
data: Additional data related to the event. This can include information about the session, function call, or other event that triggered the webhook.
Data Object Structure:
Session Events:
conversationId: The ID of the conversation.
sessionId: The ID of the session.
channelId: The ID of the channel.
channelName: The name of the channel.
createdAt: The timestamp when the session was created.
conversationThreadId: The ID of the conversation thread.
conversationTitle: The name of the conversation.
closedAt: The timestamp when the session was closed.
lastHumanActivityAt: The timestamp of the last human activity in the session.
forwardedAt: The timestamp when the session was forwarded.
forwardedToId: The ID of the agent the session was forwarded to.
forwardedToName: The name of the agent the session was forwarded to.
forwardType: The type of forwarding that occurred.
summary: The summary of the conversation.
summarizedAt: The timestamp when the conversation was summarized.
smartFields: The smart fields calculated for the conversation.
Function Call Events:
inputs: The inputs provided to the function.
functionName: The name of the function.
functionId: The ID of the function.
functionCallId: The ID of the function call.
functionStatus: The status of the function call.
sessionId: The ID of the session.
conversationId: The ID of the conversation.
conversationThreadId: The ID of the conversation thread.
app: The app data related to the function call. Only available if the function is called by an app.
metadata: The metadata of the app.
agentAppId: The ID of the particular installation of the app for a specific agent.
Set up a new webhook for events
The Darwin API provides an endpoint for configuring new webhooks, which are essential for creating real-time, event-driven integrations between the Darwin platform and external systems. Webhooks allow external services to receive notifications from Darwin immediately after specific events occur, facilitating automated processes and seamless data flows.
AUTHORIZATIONS:
Darwin API Key
REQUEST BODY SCHEMA:
application/json
Request body
webhookUrl (required, string)
The URL of the webhook to send events to.types (required, array of strings)
Items Enum:
"session.opened","session.closed","session.forwarded","session.analyzed",
"session.*","function.call.<functionName>","function.call.*","function.*"The types of events to send to the webhook. You can use wildcards to match multiple events.
Responses
201 Response body
400 Response body
Request sample (right panel)
Method: POST /v1/webhook
Request type: application/json
Payload example:
{ "webhookUrl": "https://example.com/webhook", "types": [ "session.opened", "session.closed", "session.forwarded", "session.analyzed", "session.*", "function.call.*" ] }Response samples
201 (Success):
{ "secret": "ouismdnv8329r27dsvs_2389svkjs", "webhookId": 1 }400 (Error):
application/json
Get all webhooks
The “Get all webhooks” API endpoint is designed to provide users with the ability to retrieve a comprehensive list of all the webhooks they have set up. This is particularly useful for managing and auditing webhooks, allowing users to see which events they are subscribed to.
AUTHORIZATIONS:
Darwin API Key
API Key: Darwin API Key
The API key to authenticate the request.
Header parameter name: X-API-KEY
Responses
200 Response body
Request
GET /v1/webhook
Response samples
Content type: application/json
[ { "webhookUrl": "https://example.com/webhook", "types": [ ... ] }, { "webhookUrl": "https://example.com/webhook2", "types": [ ... ] } ]Update an existing webhook
The “Update an existing webhook” operation in the Darwin API allows users to modify the settings or parameters of a webhook they have previously configured.
AUTHORIZATIONS:
Darwin API Key
PATH PARAMETERS
id (string, required) – ID of the webhook to update.
REQUEST BODY SCHEMA:
application/json
Request body
webhookUrl (string, required) – The URL of the webhook to send events to.
types (array of strings, required) –
Items Enum:"session.opened","session.closed","session.forwarded","session.analyzed","session.*","function.call.<functionName>","function.call.*","function.*"
The types of events to send to the webhook. You can use wildcards to match multiple events.
Responses
204 Response body
400 Response body
Request
PUT /v1/webhook/{id}
Request sample
Content type: application/json
{ "webhookUrl": "https://example.com/webhook", "types": [ "session.opened", "session.closed", "session.forwarded", "session.analyzed", "session.*", "function.call.*" ] }Response sample
204 Success
{}Remove an existing webhook
Removing an existing webhook refers to the process of deleting a previously configured webhook, allowing users to clean up unnecessary or outdated webhooks and maintain a streamlined integration.
AUTHORIZATIONS:
Darwin API Key
API Key: Darwin API Key
The API key to authenticate the request.
Header parameter name: X-API-KEY
PATH PARAMETERS
id (string, required) – ID of the webhook to remove.
Responses
204 Response body
400 Response body
Request
DELETE /v1/webhook/{id}
Response samples
Content type: application/json
{}