Webhooks

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

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

Webhook Destinations

Configuration

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

Capabilities

• Real-time event notifications

• Selective event subscription

• Automatic retry with exponential backoff

• Signature verification for security

• Zero-downtime secret rotation

Managing Webhook Destinations

Use these endpoints to manage your webhook destinations

Create a webhook destination

post

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

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

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

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

application/json

urlstring · uri · min: 1Required

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

accepted_typesstring[]Required

A list of webhook types to receive.

retry_attemptsinteger · min: 1 · 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.

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

HTTPcURLJavaScriptPython

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: 74

{
  "url": "https://example.com",
  "accepted_types": [
    "text"
  ],
  "retry_attempts": 3
}

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

Delete a webhook destination

delete

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

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

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

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

204

Succeeded.

No content

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or webhook destination is not found.

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

HTTPcURLJavaScriptPython

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

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

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

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

or

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

HTTPcURLJavaScriptPython

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": "2025-10-11T22:48:22.027Z",
      "retry_attempts": 1,
      "accepted_types": [
        "text"
      ]
    }
  ]
}

Get webhook deliveries

get

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

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

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:

or

nullOptional

typeany ofOptional

The type of the webhook.

stringOptional

or

nullOptional

created_afterany ofOptional

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

string · date-timeOptional

or

nullOptional

created_beforeany ofOptional

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

string · date-timeOptional

or

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 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.

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

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

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

HTTPcURLJavaScriptPython

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": "2025-10-11T22:48:22.027Z",
          "status_code": 1
        }
      ],
      "dual_signed": true,
      "created_at": "2025-10-11T22:48:22.027Z"
    }
  ],
  "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	0s	Immediate
Retry 1	5s	5s
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:

1. Receive secret when creating webhook destination

2. Amigo signs all requests with HMAC-SHA256

3. 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

Node.js Example

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)
  );
}

Python Example

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 seamless secret rotation without missing events.

Rotation Process:

Step	Action	Duration
1	Call rotation endpoint	Immediate
2	Receive new secret	Immediate
3	Dual-signing begins	30 minutes
4	Update verification logic	During dual-signing
5	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

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