Amigo is now Concurrence
Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhooks

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

Receive real-time notifications about events during client interactions with Concurrence. Webhooks let your application react immediately to conversation events, post-processing completions, and other system activities. This page covers configuring destinations, delivery and retry behavior, and signature verification; the per-event payload reference lives on Webhook Event Types.

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

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

  • 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
/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-namestring · nullableOptional

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.

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
webhook_destination_idstringRequired

The ID of the created webhook destination.

secretstringRequired

The secret used to sign the webhook event. This is only visible once and cannot be retrieved later.

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

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
webhook_destination_idstringRequired

The identifier of the webhook destination to update.

Pattern: ^[a-f0-9]{24}$
organizationstringRequired
Header parameters
x-mongo-cluster-namestring · nullableOptional

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.

Sec-WebSocket-Protocolstring[]OptionalDefault: []
Responses
204

Succeeded.

No content
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

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
Query parameters
idstring[]Optional

The IDs of the webhook destinations to retrieve.

Default: []
Header parameters
x-mongo-cluster-namestring · nullableOptional

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.

Sec-WebSocket-Protocolstring[]OptionalDefault: []
Responses
200

Succeeded.

application/json
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-01-01T00:00:00.000Z",
      "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

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
webhook_destination_idstringRequired

The identifier of the webhook destination to update.

Pattern: ^[a-f0-9]{24}$
organizationstringRequired
Header parameters
x-mongo-cluster-namestring · nullableOptional

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.

Sec-WebSocket-Protocolstring[]OptionalDefault: []
Body
retry_attemptsinteger · max: 5 · nullableOptional

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

Responses
204

Succeeded.

No content
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

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
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-namestring · nullableOptional

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.

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.

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-01-01T00:00:00.000Z"
}

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

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
webhook_destination_idstringRequired

The ID of the webhook destination whose deliveries to retrieve.

Pattern: ^[a-f0-9]{24}$
organizationstringRequired
Query parameters
statusstring · enum · nullableOptional

The status of the webhook delivery.

Possible values:
typestring · nullableOptional

The type of the webhook.

created_afterstring · date-time · nullableOptional

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

created_beforestring · date-time · nullableOptional

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

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-namestring · nullableOptional

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.

Sec-WebSocket-Protocolstring[]OptionalDefault: []
Responses
200

Succeeded.

application/json
has_morebooleanRequired

Whether there are more webhook deliveries to retrieve.

continuation_tokeninteger · nullableRequired

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

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-01-01T00:00:00.000Z",
          "status_code": 1
        }
      ],
      "dual_signed": true,
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Delivery and Retries

Automatic retry logic. Failed webhook deliveries are retried automatically with exponential backoff to keep event delivery reliable.

Default schedule (retry_attempts = 3, meaning 3 total delivery attempts):

Attempt
Delay
Total Time

Initial

0s

Immediate

Retry 1

5s

5s

Retry 2

5s

10s

  • retry_attempts bounds the total number of delivery attempts, including the initial one. Configure it on the destination with a value from 1 to 5 (default 3).

  • Backoff between attempts is exponential, clamped between 5 and 20 seconds. At the maximum setting of 5 total attempts, the waits are 5s, 5s, 5s, and 8s (about 23s total).

  • View delivery history for the past 30 days via API.

Delivery sequence

Security

Webhook signatures

Every webhook request is cryptographically signed so you can verify authenticity.

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

Signature process:

  1. Receive the secret when creating a webhook destination.

  2. Concurrence signs all requests with HMAC-SHA256.

  3. Validate the 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 (microseconds) of the delivery attempt

x-amigo-request-signature

HMAC-SHA256 signature of v1:{timestamp}:{body}

Signature verification

Secret rotation

Zero-downtime rotation. A dual-signing period lets you rotate secrets smoothly without missing events.

Rotation process:

Step
Action
Duration

1

Call the rotation endpoint

Immediate

2

Receive the 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 the dual-signing period:

  • Concurrence sends two signatures per request.

  • Accept either the old or the new signature.

  • No webhook deliveries are lost.

Rotation states

Webhook Event Types

Destinations can subscribe to API key expiration warnings, conversation post-processing completions, and agent framework resource updates. The full payload reference for each event lives on its own page.

Webhook Event Types
PreviousCommon Query Patterns
NextWebhook Event Types

Last updated

Was this helpful?