Skip to main content
POST
/
api
/
webhooks
Create Webhook
curl --request POST \
  --url https://app.tuco.ai/api/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "events": [
    "<string>"
  ],
  "name": "<string>",
  "description": "<string>"
}
'
{
  "id": "<string>",
  "secret": "<string>",
  "url": "<string>",
  "events": [
    "<string>"
  ],
  "name": "<string>",
  "createdAt": "<string>",
  "warning": "<string>"
}
Register a URL to receive real-time event notifications. The HMAC signing secret is returned once in the response. Save it immediately — you can’t retrieve it later.

​
Authentication

Authorization: Bearer tuco_sk_xxxxxxxxxxxxx

​
Request body

​
url
string
required
HTTPS endpoint URL that will receive webhook POSTs.
​
events
string[]
required
Event types to subscribe to. At least one required.
EventWhen fired
message.sentMessage accepted by Tuco
message.failedMessage failed after retries
message.fallbackRecipient has no iMessage
message.replyLead replied
message.openedMessage read (read receipt)
​
name
string
required
User-friendly name for this webhook.
​
description
string
Optional description.

​
Response

​
id
string
Webhook ID
​
secret
string
HMAC-SHA256 signing secret. Shown once. Use this to verify X-Tuco-Signature on incoming webhooks.
​
url
string
Endpoint URL
​
events
string[]
Subscribed events
​
name
string
Webhook name
​
createdAt
string
Creation timestamp (ISO UTC)
​
warning
string
Reminder to save the secret

​
Examples

curl -X POST "https://app.tuco.ai/api/webhooks" \
  -H "Authorization: Bearer tuco_sk_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/tuco",
    "events": ["message.sent", "message.failed", "message.fallback", "message.reply", "message.opened"],
    "name": "Production webhook"
  }'
201 Response
{
  "id": "680a1b2c3d4e5f6789012345",
  "secret": "dGhpcyBpcyBhIHNhbXBsZSBzZWNyZXQ=",
  "url": "https://example.com/webhooks/tuco",
  "events": ["message.sent", "message.failed", "message.fallback", "message.reply", "message.opened"],
  "name": "Production webhook",
  "description": null,
  "createdAt": "2026-04-12T12:00:00.000Z",
  "warning": "Save this secret now. You will not be able to see it again."
}
Copy the secret from the response and store it securely (e.g. environment variable). This is the only time it’s returned. If you lose it, delete the webhook and create a new one.

​
Errors

StatusWhen
400URL missing, invalid URL format, no events, invalid event types, name missing
401Invalid or missing API key
402Subscription past due (workspace is read-only)