Webhooks

Configure webhook destinations, event subscriptions, signature verification, and secret rotation.

Receive real-time notifications about events during client interactions with Amigo.

Classic API - These webhook endpoints are organization-scoped under the Classic API at api.amigo.ai.

Real-time Events Webhooks enable your application to react immediately to conversation events, post-processing completions, and other system activities.

Webhook Destinations

Feature

Details

Maximum Destinations

10 per organization

Event Filtering

Specify which event types to receive

Retry Configuration

Customize retry attempts for failed deliveries

Secret Management

Unique secret per destination for security

Managing Webhook Destinations

Use these endpoints to manage your webhook destinations

Create a webhook destination

post

/v1/{organization}/webhook_destination/

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.

Permissions

This endpoint requires the following permissions:

Webhook:CreateWebhookDestination for the webhook destination.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

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.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

urlstring · uri · min: 1Required

The URL to which the webhook will be sent. The URL must be in HTTPS.

retry_attemptsinteger · max: 5Optional

The number of attempts to retry sending the webhook event in case of failure.

Default: 3

Responses

201

Succeeded.

application/json

400

The organization already has the maximum amount of webhook destinations defined.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization is not found.

409

A related operation is in progress.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/webhook_destination/

POST /v1/{organization}/webhook_destination/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 107

{
  "url": "https://example.com",
  "accepted_types": [
    "conversation-post-processing-complete"
  ],
  "retry_attempts": 3
}

{
  "webhook_destination_id": "text",
  "secret": "text"
}

Delete a webhook destination

delete

/v1/{organization}/webhook_destination/{webhook_destination_id}

Remove a webhook destination from the organization. The webhook destination might still be active for a few seconds after this endpoint returns.

Permissions

This endpoint requires the following permissions:

Webhook:DeleteWebhookDestination for the webhook destination.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

webhook_destination_idstringRequired

The identifier of the webhook destination to update.

Pattern: ^[a-f0-9]{24}$

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

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.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

204

Succeeded.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or webhook destination is not found.

409

A related operation is in progress.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

delete

/v1/{organization}/webhook_destination/{webhook_destination_id}

DELETE /v1/{organization}/webhook_destination/{webhook_destination_id} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

No content

Get webhook destinations

get

/v1/{organization}/webhook_destination/

Retrieve this organization's webhook destinations.

Permissions

This endpoint may be impacted by the following permissions:

Webhook:GetWebhookDestination on the webhook destinations to retrieve.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

Query parameters

idstring[]Optional

The IDs of the webhook destinations to retrieve.

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

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.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

/v1/{organization}/webhook_destination/

GET /v1/{organization}/webhook_destination/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "webhook_destinations": [
    {
      "id": "text",
      "url": "text",
      "secret_generated_at": "2026-03-23T14:43:25.265Z",
      "retry_attempts": 1,
      "accepted_types": [
        "text"
      ]
    }
  ]
}

Update a webhook destination

post

/v1/{organization}/webhook_destination/{webhook_destination_id}

Update certain configs for a webhook destination. The changes will only take effect a few seconds after this endpoint returns.

The URL of a webhook destination cannot be changed. Use Create a webhook destination instead.

Permissions

This endpoint requires the following permissions:

Webhook:UpdateWebhookDestination for the webhook destination.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

webhook_destination_idstringRequired

The identifier of the webhook destination to update.

Pattern: ^[a-f0-9]{24}$

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

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.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

retry_attemptsany ofOptional

The number of attempts to retry sending the webhook event in case of failure. If not specified, this field is not updated.

integer · max: 5Optional

nullOptional

accepted_typesany ofOptional

A list of webhook types to receive. If not specified, this field is not updated.

nullOptional

Responses

204

Succeeded.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or webhook destination is not found.

409

A related operation is in progress.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/webhook_destination/{webhook_destination_id}

POST /v1/{organization}/webhook_destination/{webhook_destination_id} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 79

{
  "retry_attempts": 1,
  "accepted_types": [
    "conversation-post-processing-complete"
  ]
}

No content

URL Cannot Be Changed The URL of a webhook destination cannot be updated. To change the URL, create a new webhook destination and delete the old one.

Rotate the secret of a webhook destination

post

/v1/{organization}/webhook_destination/{webhook_destination_id}/rotate-secret

Replace the secret for the given webhook destination. The new secret will be returned and cannot be retrieved later.

Until the dual_signing_stops_at timestamp in the response, which is roughly 30 minutes after the generation of the new secret, the webhook will be signed by both the old and the new secret. This allows the webhook consumer to transition to the new secret without downtime.

The webhook rotation can occur at most once per hour for each webhook destination.

Permissions

This endpoint requires the following permissions:

Webhook:UpdateWebhookDestination for the webhook destination.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

webhook_destination_idstringRequired

The ID for the webhook destination to rotate the secret for.

Pattern: ^[a-f0-9]{24}$

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

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.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

secretstringRequired

The new secret used to sign the webhook event. This is only visible once and cannot be retrieved later. For the next 30 minutes, the webhook will be signed by both the old and the new secret.

dual_signing_stops_atstring · date-timeRequired

A UTC time where the dual-signing behavior stops. After this time, webhooks will only be signed using the new secret from this endpoint.

400

The frequency of secret rotation is limited to once per hour.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or webhook destination is not found.

409

A related operation is in progress.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/webhook_destination/{webhook_destination_id}/rotate-secret

POST /v1/{organization}/webhook_destination/{webhook_destination_id}/rotate-secret HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "secret": "text",
  "dual_signing_stops_at": "2026-03-23T14:43:25.265Z"
}

Rate Limit Secret rotation can occur at most once per hour for each webhook destination.

Get webhook deliveries

get

/v1/{organization}/webhook_destination/{webhook_destination_id}/delivery

Retrieve the webhook deliveries to a webhook destination.

Permissions

This endpoint may be impacted by the following permissions:

Webhook:GetWebhookDeliveries on the webhook deliveries to retrieve.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

webhook_destination_idstringRequired

The ID of the webhook destination whose deliveries to retrieve.

Pattern: ^[a-f0-9]{24}$

organizationstringRequired

Query parameters

statusany ofOptional

The status of the webhook delivery.

string · enumOptionalPossible values:

nullOptional

typeany ofOptional

The type of the webhook.

stringOptional

nullOptional

created_afterany ofOptional

An ISO8601 timestamp in UTC of the earliest creation time of the webhook deliveries to retrieve.

string · date-timeOptional

nullOptional

created_beforeany ofOptional

An ISO8601 timestamp in UTC of the latest creation time of the webhook deliveries to retrieve.

string · date-timeOptional

nullOptional

limitinteger · max: 50Optional

The maximum number of webhook deliveries to retrieve.

Default: 50

continuation_tokenintegerOptional

The token from the previous request to return the next page of webhook deliveries.

Default: 0

sort_bystring[]Optional

The fields to sort the sets 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.

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

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.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

has_morebooleanRequired

Whether there are more webhook deliveries to retrieve.

continuation_tokenany ofRequired

A token to supply to the next request to retrieve the next page of webhook deliveries. Only populated if has_more is True.

integerOptional

nullOptional

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or webhook destination is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

The user has exceeded the rate limit of 5 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

/v1/{organization}/webhook_destination/{webhook_destination_id}/delivery

GET /v1/{organization}/webhook_destination/{webhook_destination_id}/delivery HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "webhook_deliveries": [
    {
      "id": "text",
      "type": "text",
      "webhook_content": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "status": "success",
      "delivery_attempts": [
        {
          "delivery_time": "2026-03-23T14:43:25.265Z",
          "status_code": 1
        }
      ],
      "dual_signed": true,
      "created_at": "2026-03-23T14:43:25.265Z"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Delivery & Retries

Automatic Retry Logic Failed webhook deliveries are automatically retried with exponential backoff to ensure reliable event delivery.

Retry Attempt

Delay

Total Time

Initial

Immediate

Retry 1

Retry 2

10s

15s

Retry 3

20s

35s

Retry 4

20s

55s

Configure retry attempts via retry_attempts parameter
View delivery history for past 30 days via API

Delivery Sequence

Security

Webhook Signatures

Every webhook request is cryptographically signed to ensure authenticity.

Secret Storage Store webhook secrets securely. Never commit them to version control or expose them in client-side code.

Signature Process:

Receive secret when creating webhook destination
Amigo signs all requests with HMAC-SHA256
Validate signature on receipt to verify authenticity

Request Headers

Header

Description

x-amigo-idempotent-key

Unique identifier persisting 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}:{body}

Signature Verification

const crypto = require('crypto');

function verifyWebhookSignature(body, timestamp, signature, secret) {
  // 1. Concatenate version, timestamp, and body
  const payload = `v1:${timestamp}:${body}`;
  
  // 2. Compute HMAC-SHA256
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  // 3. Compare signatures
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

import hmac
import hashlib

def verify_webhook_signature(body, timestamp, signature, secret):
    # 1. Concatenate version, timestamp, and body
    payload = f"v1:{timestamp}:{body}"
    
    # 2. Compute HMAC-SHA256
    expected_signature = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    # 3. Compare signatures
    return hmac.compare_digest(signature, expected_signature)

Secret Rotation

Zero-Downtime Rotation Dual-signing period allows smooth secret rotation without missing events.

Rotation Process:

Step

Action

Duration

Call rotation endpoint

Immediate

Receive new secret

Immediate

Dual-signing begins

30 minutes

Update verification logic

During dual-signing

Old secret expires

After dual_signing_stops_at

During dual-signing period:

Amigo sends two signatures per request
Accept either old or new signature
No webhook deliveries are lost

Rotation States

Webhook Event Types

API Key Events

`api-key-expiration-soon`

Triggered when an API key is approaching its expiration date. Notifications fire at 14, 7, and 1 day before expiration, enabling proactive key rotation and preventing service disruptions.

Payload structure:

{
    // The webhook event type
    type: "api-key-expiration-soon",

    // Your organization's unique identifier
    org_id: string,

    // The API key that is expiring
    api_key_id: string,

    // When the API key will expire (UTC datetime)
    expiration_time: string,

    // Unique key for deduplication across retries
    idempotent_key: string
}

Proactive Key Rotation Subscribe to this event to automate key rotation workflows. Create a new API key, transition your applications, and revoke the expiring key before it becomes invalid.

Post-Processing Events

`conversation-post-processing-complete`

Triggered when asynchronous post-processing analysis completes for a conversation.

Asynchronous Processing Post-processing runs after conversations end, performing deep analysis without blocking the user experience.

Payload structure:

{
    // The webhook event type
    type: "conversation-post-processing-complete",

    // The specific post-processing operation that completed
    post_processing_type: "generate-tasks" | "generate-user-models" | "extract-memories" | "compute-metrics",

    // Unique identifier for the conversation that was analyzed
    conversation_id: string,

    // Your organization's unique identifier
    org_id: string
}

Post-Processing Types:

Type

Description

Purpose

generate-user-models

Updates L2 user model with conversation insights

Enhanced personalization

extract-memories

Stores key information as L1 observations

Future context recall

compute-metrics

Calculates performance metrics

Quality and effectiveness measurement

Processing Architecture

Live Sessions: Handle real-time interaction
Post-Processing: Performs deep analysis after conversation
No Blocking: User experience remains responsive
Async Updates: Memories, models, and metrics updated in background

PreviousCommon Query Patterns NextPermissions

Last updated 21 hours ago

Was this helpful?

Good afternoon

hashtagWebhook Destinations

hashtagManaging Webhook Destinations

hashtagCreate a webhook destination

Permissions

hashtagDelete a webhook destination

Permissions

hashtagGet webhook destinations

Permissions

hashtagUpdate a webhook destination

Permissions

hashtagRotate the secret of a webhook destination

Permissions

hashtagGet webhook deliveries

Permissions

hashtagDelivery & Retries

hashtagDelivery Sequence

hashtagSecurity

hashtagWebhook Signatures

hashtagRequest Headers

hashtagSignature Verification

hashtagSecret Rotation

hashtagRotation States

hashtagWebhook Event Types

hashtagAPI Key Events

hashtagapi-key-expiration-soon

hashtagPost-Processing Events

hashtagconversation-post-processing-complete

Webhook Destinations

Managing Webhook Destinations

Create a webhook destination

Delete a webhook destination

Get webhook destinations

Update a webhook destination

Rotate the secret of a webhook destination

Get webhook deliveries

Delivery & Retries

Delivery Sequence

Security

Webhook Signatures

Request Headers

Signature Verification

Secret Rotation

Rotation States

Webhook Event Types

API Key Events

`api-key-expiration-soon`

Post-Processing Events

`conversation-post-processing-complete`