LogoLogo
Go to website
  • Welcome
  • Getting Started
    • Amigo Overview
      • System Components
      • Overcoming LLM Limitations
      • [Advanced] Future-Ready Architecture
      • [Advanced] The Accelerating AI Landscape
    • The Journey with Amigo
      • Partnership Model
  • Concepts
    • Agent Core
      • Core Persona
      • Global Directives
    • Context Graphs
      • State-Based Architecture
      • [Advanced] Field Implementation Guidance
    • Functional Memory
      • Layered Architecture
      • User Model
      • [Advanced] Recall Mechanisms
      • [Advanced] Analytical Capabilities
    • Dynamic Behaviors
      • Side-Effect Architecture
      • Knowledge
      • [Advanced] Behavior Chaining
    • Evaluations
      • [Advanced] Arena Implementation Guide
    • [Advanced] Reinforcement Learning
    • Safety
  • Glossary
  • Advanced Topics
    • Transition to Neuralese Systems
    • Agent V2 Architecture
  • Agent Building Best Practices
    • [Advanced] Dynamic Behaviors Guide
  • Developer Guide
    • Enterprise Integration Guide
      • Authentication
      • User Creation + Management
      • Service Discovery + Management
      • Conversation Creation + Management
      • Data Retrieval + User Model Management
      • Webhook Management
    • API Reference
      • V1/organization
      • V1/conversation
      • V1/service
      • V1/user
      • V1/role
      • V1/admin
      • V1/webhook_destination
      • V1/dynamic_behavior_set
      • V1/metric
      • V1/simulation
      • Models
      • V1/organization
      • V1/service
      • V1/user
      • V1/role
      • V1/conversation
      • V1/admin
      • V1/webhook_destination
      • V1/dynamic_behavior_set
      • V1/metric
      • V1/simulation
      • Models
Powered by GitBook
LogoLogo

Resources

  • Pricing
  • About Us

Company

  • Careers

Policies

  • Terms of Service

Amigo Inc. ©2025 All Rights Reserved.


On this page

Was this helpful?

Export as PDF
  1. Developer Guide
  2. Enterprise Integration Guide

Webhook Management

PreviousData Retrieval + User Model ManagementNextAPI Reference

Last updated 21 hours ago

Was this helpful?

Webhooks

Overview

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.

Webhook Destinations

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

Managing Webhook Destinations

Use these endpoints to manage your webhook destinations

Delivery Retries

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.

Security

Webhook Signatures

Each webhook request includes a signature to verify its authenticity:

  1. When creating a webhook destination, you'll receive a secret in the response

  2. Store this secret securely - it's used to sign all webhook requests

  3. When receiving a webhook, validate the signature to confirm it came from Amigo

Headers

All webhook requests include these headers:

Header
Description

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

Signature Verification

To verify a webhook:

  1. Concatenate v1:{x-amigo-request-timestamp}:{webhook-body}

  2. Compute HMAC-SHA256 using your secret

  3. Compare with the x-amigo-request-signature header value

Secret Rotation

For enhanced security, rotate your webhook secret periodically:

  1. Call the "Rotate the secret of a webhook destination" endpoint

  2. You'll receive a new secret in the response

  3. For 30 minutes after rotation, Amigo sends two signatures with each webhook:

    • One using the old secret

    • One using the new secret

  4. This dual-signing period ends at the timestamp specified in dual_signing_stops_at

  5. Update your verification logic to accept either signature during this transition period

This approach enables zero-downtime rotation of webhook secrets.

Types of Webhooks

Amigo supports the following webhook event types that your application can subscribe to:

conversation-post-processing-complete

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

{
    // 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:

  • 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

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
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
Responses
204
Succeeded.
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
DELETE /v1/{organization}/webhook_destination/{webhook_destination_id} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
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
Path parameters
organizationstringRequired
Query parameters
idany ofOptional

The IDs of the webhook destinations to retrieve.

string[]Optional
or
nullOptional
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
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
GET /v1/{organization}/webhook_destination/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
  "webhook_destinations": [
    {
      "id": "text",
      "url": "text",
      "secret_generated_at": "2025-05-20T22:03:34.340Z",
      "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
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
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
GET /v1/{organization}/webhook_destination/{webhook_destination_id}/delivery HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
  "webhook_deliveries": [
    {
      "id": "text",
      "type": "text",
      "webhook_content": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "status": "success",
      "delivery_attempts": [
        {
          "delivery_time": "2025-05-20T22:03:34.340Z",
          "status_code": 1
        }
      ],
      "dual_signed": true,
      "created_at": "2025-05-20T22:03:34.340Z"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}
  • Webhooks
  • Overview
  • Webhook Destinations
  • POSTCreate a webhook destination
  • DELETEDelete a webhook destination
  • GETGet webhook destinations
  • GETGet webhook deliveries
  • Security
  • Types of Webhooks

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
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
Body
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
POST /v1/{organization}/webhook_destination/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 74

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