Webhooks

Overview

Webhooks push order-lifecycle events to your systems as they happen, so you can react to a provider accepting, scheduling, or completing an order without polling GET /reseller/orders. Register an HTTPS endpoint, subscribe it to the event types you care about, and Offergrid POSTs a signed JSON envelope to it every time one of those events occurs on an order your team placed.

Every delivery attempt — success or failure — is recorded and queryable via GET /reseller/webhooks/{id}/deliveries. That log is the first place to look when something appears to be missing.

Registering a webhook

The response contains the signing secret, and it is shown only once — store it before you discard the response.

curl -X POST https://api.offergrid.io/reseller/webhooks \
  -H "x-api-key: YOUR_TEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-system.example.com/offergrid-callback",
    "events": ["order.item.status_changed", "order.created"]
  }'

The url must be https:// — plain HTTP is rejected at validation.

Operation	Endpoint
Register a webhook	`POST /reseller/webhooks`
List your webhooks	`GET /reseller/webhooks`
Update url, events, or active state	`PATCH /reseller/webhooks/{id}`
Delete a webhook	`DELETE /reseller/webhooks/{id}`
Inspect delivery attempts	`GET /reseller/webhooks/{id}/deliveries`

To pause deliveries without losing the webhook or its secret, PATCH it with {"isActive": false} rather than deleting it.

Event types

Event	When it fires	Why you care
`order.item.status_changed`	A provider moved one of your order items	The main one — accepted, rejected, scheduled, completed, failed
`order.created`	An order was placed under your team	Catches orders you did not place yourself: shareable links and shop checkout
`order.item.created`	An item was added to one of your orders	Per-item detail at order time, including the provider and snapshotted price
`order.cancelled`	One of your orders was cancelled	Stop any downstream workflow

You only receive events for orders where your team is the reseller. Providers subscribe to the same four event types and receive them scoped to their offers instead — same event, different audience.If your team is hybrid, one webhook covers both roles and you receive each event exactly once. Compare providerTeamId and resellerTeamId in the payload against your own team id to tell which side of an order you are on.

Payload structure

Every delivery is a POST with Content-Type: application/json and this envelope:

{
  "id": "8f2a1c6e-...",
  "type": "order.item.status_changed",
  "version": 1,
  "data": { }
}

Field	Description
`id`	Unique event id. Use it as your idempotency key.
`type`	One of the four event types above.
`version`	Envelope version, currently `1`.
`data`	Event-specific payload, snapshotted when the event was emitted.

`order.item.status_changed`

{
  "id": "b4c3d2e1-0000-4000-8000-000000000001",
  "type": "order.item.status_changed",
  "version": 1,
  "data": {
    "orderId": "3c9d8b7a-1e2f-4a5b-8c7d-6e5f4a3b2c1d",
    "orderItemId": "7b6a5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
    "providerTeamId": "9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b",
    "resellerTeamId": "2f1e0d9c-8b7a-4655-9483-1a2b3c4d5e6f",
    "from": "pending",
    "to": "accepted",
    "orderStatus": "in_progress"
  }
}

from and to are the item’s statuses; orderStatus is the parent order’s status recomputed from all of its items — so you can update an order-level view without a follow-up read. See Order Lifecycle for the full status set.

Other event payloads

order.created, order.item.created, and order.cancelled carry the same payloads documented on the provider side: order.created · order.item.created · order.cancelled.

Verifying signatures

Signed deliveries carry a single header:

X-Offergrid-Signature: t=1767225600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

There is no separate timestamp header — the timestamp is the t= component and is also part of the signed payload, so a verifier can reject stale or replayed deliveries. The signature is HMAC-SHA256 over the string `${t}.${rawBody}`, keyed with your webhook secret, hex-encoded.

Sign over the raw request body, not a re-serialized copy. JSON.parse followed by JSON.stringify can reorder keys or change number formatting, and the signature will not match.

The scheme is identical for both roles — the worked Node and Python verifiers in Verifying signatures apply unchanged.

Delivery behaviour

Property	Behaviour
Request timeout	10 seconds. A slower endpoint is recorded as a failed attempt.
Success condition	Any 2xx response. Everything else — including 3xx — counts as a failure.
Retries	Up to 5 attempts per event with exponential backoff.
Delivery semantics	At-least-once. Expect duplicates and deduplicate on the envelope `id`.
Ordering	Not guaranteed. Reconcile against the API rather than assuming sequence.
Logging	Every attempt is logged with status code and a truncated response body.

Return 2xx as soon as you have durably accepted the event, then do the work in a background job:

app.post('/offergrid-callback', async (req, res) => {
  if (!verified(req)) return res.status(401).send('Invalid signature');

  await queue.add('offergrid-event', req.body);  // durable, fast
  res.status(200).send('OK');                    // then acknowledge
});

Deduplicate on the envelope id, which is stable across retries:

async function handleEvent(envelope: { id: string; type: string; data: unknown }) {
  const inserted = await db.processedEvents.insertIfAbsent(envelope.id);
  if (!inserted) return; // already handled

  await processEvent(envelope.type, envelope.data);
}

Testing your endpoint

Point a webhook at a tunnel while you develop:

ngrok http 4000

Register the tunnel URL, then place a test order and have the provider move it. That is the only way to exercise signature verification end to end — a hand-rolled cURL request carries no valid signature, so a correct verifier will reject it. To see what Offergrid actually sent and what your endpoint returned:

curl https://api.offergrid.io/reseller/webhooks/WEBHOOK_ID/deliveries \
  -H "x-api-key: YOUR_TEAM_API_KEY"

Still want to poll?

Webhooks do not replace reconciliation. Because delivery is at-least-once and unordered, a periodic sweep of GET /reseller/orders is a good safety net — daily is plenty once webhooks are live. See Tracking Orders.

Troubleshooting

No deliveries arriving

Confirm the webhook is isActive: true.
Confirm it subscribes to the event type you expect — a webhook only receives types listed in its events array.
Check the delivery log. Attempts with a non-2xx status mean the problem is on your side; no attempts at all means no matching event was emitted for your team.
Confirm your team is the reseller on the order. You do not receive events for orders another reseller placed, even for the same offer.

Signature verification always fails

Sign the raw body, not a re-serialized copy.
Read the timestamp from the t= component of X-Offergrid-Signature. There is no x-offergrid-timestamp header.
The signed string is the timestamp, a literal dot, then the raw body.
Compare hex-decoded buffers, checking lengths first: Node’s timingSafeEqual throws on a length mismatch.
Confirm you stored the secret from the creation response — it is shown only once and cannot be retrieved later.

Receiving the same event more than once

Expected. Delivery is at-least-once, and a retry re-sends to every subscribed target. Deduplicate on the envelope id.

Next steps

Tracking Orders

Monitoring order status in the dashboard

Order Lifecycle

Every status an order and its items can be in

Reseller API Reference

Every reseller endpoint, including webhook management

API Integration

Broader integration patterns

Getting Started

Finding Offers

Placing Orders

Managing Orders

Integration

Overview

Registering a webhook

Event types

Payload structure

`order.item.status_changed`

Other event payloads

Verifying signatures

Delivery behaviour

Testing your endpoint

Still want to poll?

Troubleshooting

Next steps

Tracking Orders

Order Lifecycle

Reseller API Reference

API Integration

​Overview

​Registering a webhook

​Event types

​Payload structure

​order.item.status_changed

​Other event payloads

​Verifying signatures

​Delivery behaviour

​Testing your endpoint

​Still want to poll?

​Troubleshooting

​Next steps

Tracking Orders

Order Lifecycle

Reseller API Reference

API Integration

Overview

Registering a webhook

Event types

Payload structure

`order.item.status_changed`

Other event payloads

Verifying signatures

Delivery behaviour

Testing your endpoint

Still want to poll?

Troubleshooting

Next steps