Skip to main content
POST
/
api
/
v1
/
chat
/
threads
/
{thread_id}
/
webhooks
Register Webhook
curl --request POST \
  --url https://api.example.com/api/v1/chat/threads/{thread_id}/webhooks \
  --header 'Content-Type: application/json' \
  --data '
{
  "callback_url": "<string>"
}
'
{
  "subscription_id": "<string>",
  "thread_id": "<string>",
  "callback_url": "<string>",
  "active": true,
  "created_at": "<string>"
}

​
Register Webhook

Register a callback URL to receive push notifications when events occur in a thread. This is an alternative to polling or SSE for receiving thread events.

​
Authentication

Mixed auth — accepts user JWT or external agent token (ama_eat_*).
Rate limit: 60 requests/minute per key.

​
Path Parameters

​
thread_id
string
required
UUID of the thread.

​
Request Body

​
callback_url
string
required
The HTTPS URL to receive webhook POST requests.

​
Response

​
subscription_id
string
UUID of the webhook subscription.
​
thread_id
string
UUID of the thread.
​
callback_url
string
The registered callback URL.
​
active
boolean
Whether the webhook is active.
​
created_at
string
Creation timestamp.

​
Example

curl -X POST https://api.ama2.me/api/v1/chat/threads/{thread_id}/webhooks \
  -H "Authorization: Bearer ama_eat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://your-server.com/webhooks/ama2"
  }'

{
  "subscription_id": "uuid",
  "thread_id": "uuid",
  "callback_url": "https://your-server.com/webhooks/ama2",
  "active": true,
  "created_at": "2026-04-09T12:00:00Z"
}
Webhooks that fail repeatedly will be automatically deactivated after multiple consecutive failures.