Skip to main content
Webhooks let you receive real-time notifications when events happen in your Tiny Talk agent. Use webhooks to integrate with custom systems, CRMs, or any tool that accepts HTTP requests.

​
Creating a webhook

  1. Go to Integrations → Webhooks in your dashboard
  2. Click Create Webhook Endpoint
  3. Enter your Webhook URL (must be HTTPS)
  4. Optionally add a Description to note what this endpoint is used for
  5. Toggle on the events you want to listen to
  6. Click Create

​
Event types

EventDescription
contact.createdA new contact is created
message.createdA new message is created (visitor, AI, or human agent)
contact.lead.updatedA contact with a lead role is updated (e.g., submitted the qualification form)
conversation.createdA new conversation is created
takeover.requestA visitor requested to speak with a human agent

​
Managing webhooks

The webhook list shows all your endpoints with their URL, source, listening event, timestamps, and active status.
  • Active toggle — Enable or disable a webhook without deleting it
  • Remove — Permanently delete a webhook endpoint
  • Click a webhook to edit its URL, description, or subscribed events

​
Webhook secret and signature verification

Each webhook endpoint has a Webhook Secret (visible when editing the endpoint). Use this secret to verify that incoming requests are genuinely from Tiny Talk. Tiny Talk signs the request body with the webhook secret and includes the signature in the TinyTalk-Signature header. To verify:
  1. Compute an HMAC-SHA256 hash of the raw request body using your webhook secret
  2. Compare it to the value in the TinyTalk-Signature header
Each request also includes an Idempotency-Key header that you can use to detect and handle duplicate deliveries.

​
Testing webhooks

Each event has a Test button (lightning icon) that sends a sample payload to your endpoint. Use this to verify your integration is working before going live. For development, tools like webhook.site or ngrok are useful for inspecting payloads without setting up a server.

​
Payload format

Webhook payloads are sent as POST requests with a JSON body. The exact structure varies by event type — use the Test button to inspect sample payloads for each event.

​
Retry behavior

If your endpoint returns a non-2xx response, Tiny Talk may retry the delivery. Ensure your endpoint:
  • Responds with a 200 status code on success
  • Handles duplicate events gracefully (use the Idempotency-Key header for deduplication)
  • Responds within 30 seconds
Webhooks created by Zapier and Pabbly Connect integrations also appear in the webhook list, marked with their source. Modifying or deleting these webhooks may break those integrations.