Webhooks

Overview

Webhooks push order-lifecycle events to your systems as they happen, so you can start fulfillment without polling GET /provider/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 that includes one of your offers.

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

Registering a webhook

Create the webhook with the Provider API. 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/provider/webhooks \
  -H "x-api-key: YOUR_TEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://provider-system.example.com/offergrid-callback",
    "events": ["order.item.created", "order.item.status_changed"]
  }'

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

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

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

Event types

These are the six event types you can subscribe to. Subscribing to a type not on this list is rejected.

Event	When it fires	Scoped to
`order.item.created`	A reseller ordered one of your offers	The provider that owns the item
`order.item.status_changed`	An item’s fulfillment status changed	The provider that owns the item
`order.created`	An order was placed	Every provider with an item on that order
`order.cancelled`	An order was cancelled	Every provider with an item on that order
`order.consent_recorded`	The customer made a contact-consent decision at checkout that names your team	Each provider named in the disclosure
`order.consent_revoked`	A previously granted consent naming your team was withdrawn	Each provider named in the disclosure

order.item.created is the one to build fulfillment on. It carries the specific item you need to fulfill; order.created describes the order as a whole, which may span several providers.order.consent_recorded is the record to keep before you dial: it carries the exact disclosure text the customer saw, the number it binds to, and whether marketing calls/texts were granted. order.consent_revoked is the signal to stop — honour it within ten business days. See Contact consent.Resellers subscribe to these same types on their own endpoint and receive them scoped to the orders they placed — see Reseller webhooks. If your team is hybrid, one webhook covers both roles and each event is delivered exactly once.

Payload structure

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

{
  "id": "8f2a1c6e-...",
  "type": "order.item.created",
  "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`. Bumped only on an incompatible change to an existing type’s payload.
`data`	Event-specific payload, snapshotted at the time the event was emitted.

Payloads snapshot order-time data — offer name, price, address, customer info — rather than referencing live rows, so a delivery stays accurate even if the offer changes afterwards.

`order.item.created`

{
  "id": "8f2a1c6e-4b2d-4d0a-9a7f-2c8f1e3b5a90",
  "type": "order.item.created",
  "version": 1,
  "data": {
    "orderId": "3c9d8b7a-1e2f-4a5b-8c7d-6e5f4a3b2c1d",
    "orderItemId": "7b6a5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
    "offerId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "offerName": "High-Speed Internet 1000 Mbps",
    "category": "internet",
    "monthlyPrice": "79.99",
    "promoMonthlyPrice": "49.99",
    "contractLength": "12_months",
    "providerTeamId": "9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b",
    "resellerTeamId": "2f1e0d9c-8b7a-4655-9483-1a2b3c4d5e6f"
  }
}

`order.item.status_changed`

{
  "id": "b4c3d2e1-...",
  "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.

`order.created`

{
  "id": "c5d4e3f2-...",
  "type": "order.created",
  "version": 1,
  "data": {
    "orderId": "3c9d8b7a-1e2f-4a5b-8c7d-6e5f4a3b2c1d",
    "resellerTeamId": "2f1e0d9c-8b7a-4655-9483-1a2b3c4d5e6f",
    "linkId": null,
    "serviceAddress": {
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zipCode": "94102"
    },
    "customerInfo": {
      "firstName": "Jordan",
      "lastName": "Reyes",
      "email": "jordan@example.com",
      "phone": "+14155550123"
    },
    "totalMonthly": "129.98"
  }
}

`order.cancelled`

{
  "id": "d6e5f4a3-...",
  "type": "order.cancelled",
  "version": 1,
  "data": {
    "orderId": "3c9d8b7a-1e2f-4a5b-8c7d-6e5f4a3b2c1d",
    "resellerTeamId": "2f1e0d9c-8b7a-4655-9483-1a2b3c4d5e6f",
    "orderStatus": "cancelled"
  }
}

`order.consent_recorded`

One event per consent decision that names your team. kind is order_contact (transactional — you may contact the customer about this order) or marketing_calls_texts (TCPA prior express written consent for autodialed/prerecorded marketing calls and texts). A declined marketing decision is delivered too, with granted: false.

{
  "id": "e7f6a5b4-...",
  "type": "order.consent_recorded",
  "version": 1,
  "data": {
    "orderId": "3c9d8b7a-1e2f-4a5b-8c7d-6e5f4a3b2c1d",
    "consentRecordId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "kind": "marketing_calls_texts",
    "channel": "shop",
    "granted": true,
    "providerTeamId": "your-team-id",
    "providerTeamIds": ["your-team-id"],
    "phoneE164": "+14155550123",
    "email": "jordan@example.com",
    "disclosureVersion": "marketing_calls_texts.v1",
    "disclosureText": "Yes, Acme Fiber may also call and text me at (415) 555-0123 with offers and promotions, including by using an autodialer and prerecorded or artificial-voice messages. I understand that this consent is not a condition of purchase, that message and data rates may apply, and that I can revoke it at any time by replying STOP to any text message or at https://offergrid.io/opt-out.",
    "recordedAt": "2026-09-03T14:02:11.000Z"
  }
}

`order.consent_revoked`

Same payload as order.consent_recorded, plus revokedAt and revokedVia (web_form for offergrid.io/opt-out, provider_report when another party reported a STOP through the API). Treat the number as do-not-contact for marketing from this moment; you may still contact the customer to fulfil an order they placed.

{
  "id": "f8a7b6c5-...",
  "type": "order.consent_revoked",
  "version": 1,
  "data": {
    "orderId": "3c9d8b7a-1e2f-4a5b-8c7d-6e5f4a3b2c1d",
    "consentRecordId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "kind": "marketing_calls_texts",
    "channel": "shop",
    "granted": true,
    "providerTeamId": "your-team-id",
    "providerTeamIds": ["your-team-id"],
    "phoneE164": "+14155550123",
    "email": "jordan@example.com",
    "disclosureVersion": "marketing_calls_texts.v1",
    "disclosureText": "…",
    "recordedAt": "2026-09-03T14:02:11.000Z",
    "revokedAt": "2026-09-10T09:30:00.000Z",
    "revokedVia": "web_form"
  }
}

Verifying signatures

Signed deliveries carry a single header:

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

There is no separate timestamp header — the timestamp lives in the t= component and is also part of the signed payload, so a verifier can reject stale or replayed deliveries without any shared clock beyond a tolerance window. 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. Capture the raw bytes before body parsing.

import crypto from 'crypto';
import express from 'express';

const app = express();

// Capture the raw body — express.json() alone gives you a parsed object,
// which cannot be re-serialized back to the exact signed bytes.
app.use(express.json({ verify: (req, _res, buf) => { (req as any).rawBody = buf; } }));

function verifySignature(rawBody: Buffer, header: string, secret: string): boolean {
  const parts = Object.fromEntries(
    header.split(',').map((part) => part.split('=') as [string, string]),
  );
  const timestamp = Number(parts.t);
  const signature = parts.v1;
  if (!timestamp || !signature) return false;

  // Reject deliveries older than 5 minutes (replay protection).
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody.toString('utf8')}`)
    .digest('hex');

  const expectedBuffer = Buffer.from(expected, 'hex');
  const actualBuffer = Buffer.from(signature, 'hex');
  // timingSafeEqual throws on length mismatch — check first.
  if (expectedBuffer.length !== actualBuffer.length) return false;
  return crypto.timingSafeEqual(expectedBuffer, actualBuffer);
}

app.post('/offergrid-callback', (req, res) => {
  const header = req.headers['x-offergrid-signature'] as string | undefined;
  if (!header || !verifySignature((req as any).rawBody, header, process.env.OFFERGRID_WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature');
  }

  // Acknowledge first, process asynchronously.
  void enqueue(req.body);
  res.status(200).send('OK');
});

import hashlib, hmac, os, time
from flask import Flask, request

app = Flask(__name__)

def verify_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(part.split("=", 1) for part in header.split(","))
    try:
        timestamp = int(parts["t"])
        signature = parts["v1"]
    except (KeyError, ValueError):
        return False

    # Reject deliveries older than 5 minutes (replay protection).
    if abs(int(time.time()) - timestamp) > 300:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.post("/offergrid-callback")
def callback():
    header = request.headers.get("X-Offergrid-Signature", "")
    if not verify_signature(request.get_data(), header, os.environ["OFFERGRID_WEBHOOK_SECRET"]):
        return "Invalid signature", 401

    enqueue(request.get_json())
    return "OK", 200

One case is unsigned: if an offer has a submissionUrl and your team has no registered webhook at all, order.item.created is delivered to that URL without a signature, because there is no secret to sign with. Register a webhook — even an inactive one — to get signed submissions.

Delivery behaviour

What Offergrid guarantees from the sending side:

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. Do not assume `order.item.created` arrives before its first `order.item.status_changed`.
Logging	Every attempt is written to the delivery log with status code and a truncated response body, whether it succeeded or not.

Retries are per-event, not per-target. If you have several webhooks subscribed to the same event and one fails, the retry re-sends to all of them — which is another reason to deduplicate on the envelope id.

Responding

Return 2xx as soon as you have durably accepted the event, and do the real work in a background job. You have 10 seconds, but treating that as a budget rather than a target keeps you off the retry path.

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
});

Deduplicating

async function handleEvent(envelope: { id: string; type: string; data: unknown }) {
  // The envelope id is stable across retries — the natural idempotency key.
  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 from a reseller account to trigger a real, correctly-signed delivery. This 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 confirm what Offergrid actually sent and what your endpoint returned:

curl https://api.offergrid.io/provider/webhooks/{webhookId}/deliveries \
  -H "x-api-key: YOUR_TEAM_API_KEY"

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. If attempts are recorded with a non-2xx status, the problem is on your side; if there are no attempts at all, no matching event was emitted for your team.
Confirm the order actually contains one of your offers — item-scoped events only go to the provider that owns the item.

Signature verification always fails

Sign the raw body, not a re-serialized copy.
Parse the timestamp out of the t= component of X-Offergrid-Signature. There is no x-offergrid-timestamp header.
The signed string is `${t}.${rawBody}` — the timestamp, a literal dot, then the body.
Compare hex-decoded buffers, and check 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.

Deliveries recorded as failed with no status code

A null status code means the request never completed — DNS failure, TLS error, connection refused, or your endpoint exceeded the 10-second timeout. The recorded response body holds the underlying error message.

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

Receiving Orders

What to do with an order once the webhook lands

Order Workflow

The status lifecycle behind order.item.status_changed

Provider API Reference

Every provider endpoint, including webhook management

API Integration

Broader integration patterns

Getting Started

Managing Offers

Order Fulfillment

Partner Management

Integration

Overview

Registering a webhook

Event types

Payload structure

`order.item.created`

`order.item.status_changed`

`order.created`

`order.cancelled`

`order.consent_recorded`

`order.consent_revoked`

Verifying signatures

Delivery behaviour

Responding

Deduplicating

Testing your endpoint

Troubleshooting

Next steps

Receiving Orders

Order Workflow

Provider API Reference

API Integration

​Overview

​Registering a webhook

​Event types

​Payload structure

​order.item.created

​order.item.status_changed

​order.created

​order.cancelled

​order.consent_recorded

​order.consent_revoked

​Verifying signatures

​Delivery behaviour

​Responding

​Deduplicating

​Testing your endpoint

​Troubleshooting

​Next steps

Receiving Orders

Order Workflow

Provider API Reference

API Integration

Overview

Registering a webhook

Event types

Payload structure

`order.item.created`

`order.item.status_changed`

`order.created`

`order.cancelled`

`order.consent_recorded`

`order.consent_revoked`

Verifying signatures

Delivery behaviour

Responding

Deduplicating

Testing your endpoint

Troubleshooting

Next steps