Webhooks

Webhooks let you receive real-time HTTP notifications when events occur on your account — such as an order being delivered or a payout completing. Instead of polling the API, your server receives a POST request with the event data the moment it happens.

How It Works

1. An event occurs (e.g. order delivered)
2. Octopus sends a POST request to your registered URL
3. Your server processes the event and returns 2xx
4. If delivery fails, we retry with exponential backoff

Configuration

Webhooks are configured through your client dashboard. For each webhook you provide:

Field	Description
URL	Your HTTPS endpoint that receives events (HTTPS required)
Secret	A shared secret used to sign payloads — keep this secure
Events	Which event types to subscribe to

You can register multiple webhook URLs, each subscribed to different events.

Payload Format

Every webhook delivers a JSON payload with a standard envelope:

{
  "id": "evt_abc123",
  "type": "order.delivered",
  "created_at": "2025-01-15T14:30:00Z",
  "data": {
    // Event-specific fields
  }
}

Field	Type	Description
`id`	string	Unique event ID — use this for idempotent processing
`type`	string	Event type (e.g. `order.delivered`)
`created_at`	string	When the event was created (RFC 3339)
`data`	object	Event-specific payload (varies by event type)

HTTP Request

Webhooks are sent as POST requests with these headers:

Header	Description
`Content-Type`	`application/json`
`User-Agent`	`octopusrewards.com/webhook-agent`
`X-OCTOPUS-WEBHOOK-TOKEN`	Your shared secret (for quick verification)
`X-Webhook-ID`	Webhook configuration ID
`X-Event-ID`	Unique event ID (same as `id` in payload)
`X-Event-Type`	Event type (same as `type` in payload)
`X-Timestamp`	Unix timestamp of when the webhook was sent
`X-Signature`	HMAC-SHA256 signature of the payload body

Delivery & Retries

Parameter	Value
Timeout	30 seconds
Success	Any HTTP 2xx status code
Max attempts	5 retries (6 total attempts)
Backoff	Exponential — 1 min, 2 min, 4 min, 8 min, 16 min

If all attempts fail, the delivery is marked as permanently failed. You can view delivery history and failure details in your dashboard.

Your endpoint must respond within 30 seconds with a 2xx status code. If it returns a non-2xx status or times out, the delivery is retried. Make sure your webhook handler is fast — offload heavy processing to a background queue.

Idempotency

Each event has a unique id (e.g. evt_abc123). The same event may be delivered more than once due to retries. Always check the event id against your records and skip duplicates to ensure idempotent processing.

// Example: deduplicate by event ID
if alreadyProcessed(event.ID) {
    return http.StatusOK // Acknowledge but skip
}
processEvent(event)
markProcessed(event.ID)