Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
What are webhooks?

Webhooks push real-time event notifications to URLs you control. Instead of polling the API, your systems receive a POST request the moment something happens — a message sends, fails, gets a reply, or is read.

​
How it works

1

Register a webhook

Call Create Webhook with your endpoint URL and the events you care about. Save the signing secret from the response — it’s shown once.
2

Receive events

Tuco sends a signed POST to your URL whenever a subscribed event fires. Verify the X-Tuco-Signature header using your secret.
3

Return 2xx quickly

Acknowledge the webhook with a 2xx response within a few seconds. Do heavy processing asynchronously.

​
Available events

EventFired when
message.sentMessage accepted and sent by Tuco
message.failedMessage failed after all retries (technical error)
message.fallbackRecipient doesn’t have iMessage (business outcome, not error)
message.replyLead or contact replied to your message
message.openedMessage was read (read receipt, where supported)
See Message Webhooks for full payload details, example bodies, and field-by-field documentation for each event.

​
Management API

Full CRUD for webhook registrations. All endpoints require Bearer token auth.

List Webhooks

GET /api/webhooks — See all webhooks in your workspace

Create Webhook

POST /api/webhooks — Register a new endpoint

Get Webhook

GET /api/webhooks/{id} — Get details for one webhook

Update Webhook

PATCH /api/webhooks/{id} — Change URL, events, or status

Delete Webhook

DELETE /api/webhooks/{id} — Remove a webhook permanently

Test Webhook

POST /api/webhooks/{id}/health-check — Fire a test ping

​
Security

Every webhook POST includes three headers for verification:
HeaderPurpose
X-Tuco-SignatureHMAC-SHA256 hex digest of the request body, signed with your webhook secret
X-Tuco-EventEvent type (e.g. message.sent)
X-Tuco-TimestampWhen the webhook was fired (ISO UTC)
Always verify X-Tuco-Signature before processing. See signature verification code examples in the Message Webhooks page.

​
Delivery behavior

Webhooks are fire-and-forget. Tuco sends each event once and does not retry on failure. Make sure your endpoint is reliable and returns 2xx quickly.
  • Parallel delivery — if you have multiple webhooks subscribed to the same event, all receive the POST simultaneously
  • 10-second timeout — if your endpoint doesn’t respond within 10 seconds, the delivery is marked as failed
  • No retry — failed deliveries are logged but not retried. Use the Test Webhook endpoint to verify your setup
  • Failure tracking — failureCount, lastSuccessAt, and lastFailureAt on the webhook object let you monitor health
Use Test Webhook after creating or updating a webhook to confirm your endpoint is reachable and your signature verification works.