Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usetitan.app/llms.txt

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

Webhooks let you receive real-time notifications from Titan. When an event occurs — a message arrives, a session connects, or a group changes — Titan sends an HTTP POST request to your registered URL with a JSON payload describing what happened. You do not need to poll the API.

​
How webhook delivery works

Every delivery is a POST request to your URL with:
  • Content-Type: application/json
  • X-Webhook-Signature: sha256={hex_digest} — HMAC-SHA256 signature you use to verify the request came from Titan
  • A JSON body containing the event type, session name, timestamp, and event-specific payload
Titan expects a 2xx response from your server to consider the delivery successful. If your server returns a non-2xx status or does not respond within the timeout, Titan retries the delivery according to your retry policy.

​
Setting up webhooks

1

Create a webhook

Call POST /api/webhooks with the URL you want Titan to deliver events to. At minimum you need a url. Everything else is optional.
curl -X POST https://api.titan.whiskey.so/api/webhooks \
  -H "Authorization: Bearer titan_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhooks/titan",
    "events": ["message.received", "session.status"],
    "label": "My Webhook",
    "hmacKey": "your-secret-signing-key"
  }'
Titan returns the created webhook object including its id.
2

Verify signatures

Every delivery includes an X-Webhook-Signature header. Verify it before processing the payload to ensure the request came from Titan and was not tampered with. See Signature verification for code examples.
3

Handle events

Parse the JSON body and branch on the event field. Return a 2xx response as quickly as possible — do your processing asynchronously if it takes time. See Event reference for the complete list of events and their payload structures.

​
Webhook configuration

​
Request body for POST /api/webhooks

​
url
string
required
The HTTPS URL Titan delivers events to. Private IPs, localhost, and internal hostnames are blocked by SSRF protection.
​
events
string[]
Array of event type strings to subscribe to (for example, ["message.received", "session.status"]). Pass ["*"] or omit this field to receive all events. See Event reference for the full list.
​
hmacKey
string
Secret key used to compute the X-Webhook-Signature HMAC-SHA256 header on every delivery. Keep this value private. If you omit it, Titan auto-generates one and includes it in the response — store it immediately, as it is not shown again.
​
headers
object[]
Up to 10 custom HTTP headers to include with each delivery. Useful for adding an authentication header your server expects.
"headers": [
  { "name": "X-Secret", "value": "my-secret" },
  { "name": "X-Source", "value": "titan" }
]
Each header object has a name and value field.
​
retries
object
Configures how Titan retries failed deliveries.
"retries": {
  "attempts": 3,
  "delaySeconds": 5,
  "policy": "exponential"
}
FieldTypeDescription
attemptsintegerMaximum number of retry attempts after the first failure
delaySecondsintegerInitial delay between retries in seconds
policystringBackoff strategy: constant, linear, or exponential
With exponential policy and delaySeconds: 5, retries happen at 5 s, 10 s, 20 s, and so on.
​
session
string
Session name to filter events for. When set, Titan only delivers events from that specific session. Omit to receive events from all sessions.
Webhook URLs must use HTTPS and must not resolve to a private IP address, localhost, or an internal hostname. Titan validates URLs on creation and rejects those that fail SSRF checks.

​
Webhook payload envelope

Every event Titan delivers uses the same envelope structure: 
{
  "id": "evt_abc123",
  "event": "message.received",
  "session": "my-session",
  "timestamp": "2025-01-15T10:30:00Z",
  "payload": { ... }
}
​
id
string
Unique identifier for this delivery attempt.
​
event
string
The event type, for example message.received or session.status. Use this field to route the payload to the correct handler.
​
session
string
Name of the Titan session that produced the event.
​
timestamp
string
ISO 8601 timestamp of when the event occurred.
​
payload
object
Event-specific data. The structure differs per event type. See Event reference.

​
Managing webhooks

OperationEndpoint
List all webhooksGET /api/webhooks
Get a webhook by IDGET /api/webhooks/{id}
Update a webhookPUT /api/webhooks/{id}
Delete a webhookDELETE /api/webhooks/{id}
You can update any field on an existing webhook, including the URL, subscribed events, headers, retry policy, and whether the webhook is enabled or disabled. 
# Disable a webhook temporarily
curl -X PUT https://api.titan.whiskey.so/api/webhooks/42 \
  -H "Authorization: Bearer titan_..." \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'
Creating and managing webhooks requires the webhooks:manage scope on your API key.

​
Retry policies

When your server returns a non-2xx response or does not respond in time, Titan retries the delivery using the policy you configured.
PolicyBehavior
constantSame delay between every retry
linearDelay increases by delaySeconds on each attempt
exponentialDelay doubles on each attempt
For development, you can use a tool like Webhook.site or ngrok to inspect webhook payloads before wiring up your production server.

​
Next steps

Event reference

Browse all 30 event types, organized by category, with example payloads for each.

Signature verification

Learn how to verify the HMAC-SHA256 signature in TypeScript, Python, Go, and PHP.