Webhook Management
Last updated
Was this helpful?
Last updated
Was this helpful?
Webhooks allow you to receive real-time notifications about events during client interactions with Amigo. This guide explains how to set up, secure, and manage webhooks for your application.
Your organization can configure up to 10 webhook destination URLs. For each destination, you can specify:
Event types to receive
Number of retry attempts for failed deliveries
Use these endpoints to manage your webhook destinations
If the initial webhook delivery fails, Amigo automatically retries with exponential backoff:
Up to 4 additional retry attempts (configurable via retry_attempts)
Retry intervals: 5, 10, 20, and 20 seconds
You can view all webhook delivery attempts from the past 30 days using the "Get webhook deliveries" endpoint.
Each webhook request includes a signature to verify its authenticity:
When creating a webhook destination, you'll receive a secret in the response
Store this secret securely - it's used to sign all webhook requests
When receiving a webhook, validate the signature to confirm it came from Amigo
All webhook requests include these headers:
x-amigo-idempotent-key
Unique identifier that persists through retries for deduplication
x-amigo-request-timestamp
UNIX timestamp (milliseconds) of the delivery attempt
x-amigo-request-signature
HMAC-SHA256 signature of v1:{timestamp}:{webhook-body} using your secret
To verify a webhook:
Concatenate v1:{x-amigo-request-timestamp}:{webhook-body}
Compute HMAC-SHA256 using your secret
Compare with the x-amigo-request-signature header value
For enhanced security, rotate your webhook secret periodically:
Call the "Rotate the secret of a webhook destination" endpoint
You'll receive a new secret in the response
For 30 minutes after rotation, Amigo sends two signatures with each webhook:
One using the old secret
One using the new secret
This dual-signing period ends at the timestamp specified in dual_signing_stops_at
Update your verification logic to accept either signature during this transition period
This approach enables zero-downtime rotation of webhook secrets.
Amigo supports the following webhook event types that your application can subscribe to:
conversation-post-processing-completeThis webhook is emitted when any post-processing analysis for a conversation has completed successfully. Post-processing operations run asynchronously after conversations conclude and perform various analytical functions.
Payload structure:
Post-processing types:
generate-tasks: Analyzes completed conversations to identify actionable tasks based on conversation content and commitments made.
generate-user-models: Updates the L2 user model by synthesizing insights from the conversation, enhancing future personalization and contextual awareness.
extract-memories: Identifies and stores key information as structured memories in the L1 observations layer for future recall.
compute-metrics: Calculates conversation performance metrics based on your configured evaluation criteria to measure effectiveness and quality.
These post-processing operations are part of Amigo's separation between live session systems (which handle real-time interactions) and post-processing systems (which perform deeper analysis after sessions conclude). For more information, see Live Session vs. Post-Processing.
Remove a webhook destination from the organization. The webhook destination might still be active for a few seconds after this endpoint returns.
This endpoint requires the following permissions:
User:GetUserInfo for the authenticated user.Webhook:DeleteWebhookDestination for the webhook destination.The identifier of the webhook destination to update.
^[a-f0-9]{24}$The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
No body
Retrieve this organization's webhook destinations.
This endpoint requires the following permissions:
User:GetUserInfo on the authenticated user.This endpoint may be impacted by the following permissions:
Webhook:GetWebhookDestination on the webhook destinations to retrieve.The IDs of the webhook destinations to retrieve.
The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
Retrieve the webhook deliveries to a webhook destination.
This endpoint requires the following permissions:
User:GetUserInfo on the authenticated user.This endpoint may be impacted by the following permissions:
Webhook:GetWebhookDeliveries on the webhook deliveries to retrieve.The ID of the webhook destination whose deliveries to retrieve.
^[a-f0-9]{24}$The status of the webhook delivery.
The type of the webhook.
An ISO8601 timestamp in UTC of the earliest creation time of the webhook deliveries to retrieve.
An ISO8601 timestamp in UTC of the latest creation time of the webhook deliveries to retrieve.
The maximum number of webhook deliveries to retrieve.
50The token from the previous request to return the next page of webhook deliveries.
0The fields to sort the webhook deliveries by. Supported fields are type, status, and created_at. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.
[]The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
Create a new webhook destination. At most 10 webhook destinations can be defined per organization.
A secret will immediately be issued for the webhook destination. Every webhook sent to this destination will be signed using this secret. This secret is one-view only and cannot be retrieved later.
This endpoint requires the following permissions:
User:GetUserInfo for the authenticated user.Webhook:CreateWebhookDestination for the webhook destination.The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
The URL to which the webhook will be sent.
A list of webhook types to receive.
The number of attempts to retry sending the webhook event in case of failure.
3