Webhooks

#Quick Start

#How Webhooks Work

1. You register a webhook URL in Tracktile
2. Tracktile generates a unique signing secret for your webhook
3. When an event occurs, Tracktile sends a signed HTTP POST to your URL
4. Your server verifies the signature and processes the event

All webhook payloads are signed with HMAC-SHA256. See Webhook Security for verification details.

#Setting Up Webhooks

#Via API

curl -X POST "https://api.tracktile.io/hooks" \
  -H "Authorization: Bearer api-YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Webhook",
    "url": "https://your-server.com/webhook",
    "on": ["order.status.changed"]
  }'

The response includes a secret field—save it immediately as it's only shown once. You'll need this secret to verify webhook signatures.

#Via CLI

tt webhooks register \
  --name="My Webhook" \
  --on="order.status.changed" \
  --url="https://your-server.com/webhook"

#Via the Tracktile App

1. Navigate to Admin > Settings > Webhooks
2. Click Create Webhook
3. Enter the webhook name, URL, and select the events to subscribe to

#Managing Webhooks

#List Webhooks

curl "https://api.tracktile.io/hooks" \
  -H "Authorization: Bearer api-YOUR_TOKEN_HERE"

#Update a Webhook

curl -X PUT "https://api.tracktile.io/hooks/{id}" \
  -H "Authorization: Bearer api-YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Webhook",
    "status": "paused"
  }'

#Delete a Webhook

curl -X DELETE "https://api.tracktile.io/hooks/{id}" \
  -H "Authorization: Bearer api-YOUR_TOKEN_HERE"

#Rotate a Webhook Secret

If your webhook secret is compromised, rotate it immediately:

curl -X POST "https://api.tracktile.io/hooks/{id}/rotate" \
  -H "Authorization: Bearer api-YOUR_TOKEN_HERE"

The old secret is immediately invalidated. Save the new secret from the response.

#Webhook Payload Structure

All webhook payloads are sent as JSON with event-specific data:

{
  "id": "evt_abc123",
  "kind": "order.status.changed",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "orderId": "ord_456",
  "previousOrderStatus": "pending",
  "currentOrderStatus": "confirmed"
}

The payload structure varies by event type. See the Event Catalog for details on each event.

#Testing Webhooks

Use the test endpoint to verify your webhook is configured correctly:

curl -X POST "https://api.tracktile.io/hooks/{id}/test" \
  -H "Authorization: Bearer api-YOUR_TOKEN_HERE"

This sends a test event to your webhook URL.

#Webhook Status

Webhooks can have the following statuses:

#Execution History

View recent webhook executions:

curl "https://api.tracktile.io/hooks/{id}/executions" \
  -H "Authorization: Bearer api-YOUR_TOKEN_HERE"

Returns the execution history including HTTP status codes and response details.

#Event Types

See the Event Catalog for all available event types.