Webhooks

Webhooks

23 events

Real-time event notifications from Tracktile. Receive instant updates when orders change, shipments move, or inventory shifts.

Quick Start

Event Catalog

Browse all available webhook events

Security

Verify webhook signatures and secure your endpoints

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

Register webhook bash

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

Register webhook bash

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 event type

Managing Webhooks

List Webhooks

List all webhooks bash

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

Update a Webhook

Update webhook bash

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

Delete webhook bash

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:

Rotate secret bash

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:

Example payload json

{
  "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:

Test webhook bash

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:

Status Values

active

string

Webhook is enabled and receiving events

paused

string

Webhook is disabled and not receiving events

Execution History

View recent webhook executions:

Get execution history bash

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.