V1/webhook_destination

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-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

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

HTTPcURLJavaScriptPython

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-23T17:56:09.181Z",
      "retry_attempts": 1,
      "accepted_types": [
        "text"
      ]
    }
  ]
}

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-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-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

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

HTTPcURLJavaScriptPython

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"
}

Update a webhook destination

post

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

Bearer-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-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

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 · min: 1 · max: 5Optional

or

nullOptional

accepted_typesany ofOptional

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

string[]Optional

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 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/{webhook_destination_id} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 46

{
  "retry_attempts": 1,
  "accepted_types": [
    "text"
  ]
}

No content

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-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-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

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

HTTPcURLJavaScriptPython

DELETE /v1/{organization}/webhook_destination/{webhook_destination_id} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*

No content

Rotate the secret of a webhook destination

post

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

Bearer-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

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

or

nullOptional

Responses

200

Succeeded.

application/json

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.

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

HTTPcURLJavaScriptPython

POST /v1/{organization}/webhook_destination/{webhook_destination_id}/rotate-secret HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*

{
  "secret": "text",
  "dual_signing_stops_at": "2025-05-23T17:56:09.181Z"
}

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-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-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

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 JWT
Accept: */*

{
  "webhook_deliveries": [
    {
      "id": "text",
      "type": "text",
      "webhook_content": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "status": "success",
      "delivery_attempts": [
        {
          "delivery_time": "2025-05-23T17:56:09.181Z",
          "status_code": 1
        }
      ],
      "dual_signed": true,
      "created_at": "2025-05-23T17:56:09.181Z"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}