Skip to main content

​
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

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: 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.