Webhook Guides

Webhook Payload Example

A webhook payload is the request body a provider sends when an event happens. Most payloads are JSON, but the useful fields vary by provider: event id, event type, created time, data object, account or tenant id, and sometimes retry or delivery metadata.

FastHook stores payloads with their headers, path, query params, routed events, and destination attempts. That makes examples useful not just for coding a receiver, but also for testing filters, transformations, idempotency, and replay behavior.

Generic webhook payload

JSON payload
{
  "id": "evt_123",
  "type": "invoice.paid",
  "created_at": "2026-06-17T10:00:00Z",
  "data": {
    "invoice_id": "inv_001",
    "customer_id": "cus_42",
    "amount": 4900,
    "currency": "USD"
  }
}

cURL request with headers

Webhook request
curl -X POST "https://hook-xxxxxx.fasthook.io/" \
  -H "Content-Type: application/json" \
  -H "X-Event-Type: invoice.paid" \
  -H "X-Delivery-Id: del_123" \
  -d '{
    "id": "evt_123",
    "type": "invoice.paid",
    "data": {
      "invoice_id": "inv_001",
      "amount": 4900
    }
  }'

Fields to include

FieldWhy it matters
idBest first choice for idempotency.
typeLets receivers and filters branch by event family.
created_atUseful for replay windows and stale-event checks.
dataHolds the business object that changed.
account or tenant idRoutes multi-tenant traffic safely.

Filter by payload

Body filter
{
  "type": "filter",
  "body": {
    "type": { "$eq": "invoice.paid" },
    "data.currency": { "$eq": "USD" }
  }
}

Payload debugging

  • Compare the captured payload to the provider docs and real production examples.
  • Do not assume optional fields always exist.
  • Use event id or delivery id before creating side effects.
  • Keep raw body behavior intact for signature verification.
  • Replay one stored event after changing parsing or transformation logic.

Bad payload examples to test

Good tests include payloads that should fail safely. A receiver that only sees perfect fixtures may break when a provider omits optional fields, sends a new event type, changes an enum value, or sends a retry for an object that has already been processed.

  • Missing optional nested object, such as customer or line_items.
  • Unknown event type that should be ignored or routed to a review destination.
  • Duplicate id with a different provider delivery id.
  • Payload that is valid JSON but fails business validation.
  • Large payload that should be accepted quickly and processed asynchronously.

Use payload examples in CI

Store a small set of provider payload examples with your receiver tests. When filters or transformations change, replay those examples through a mock or local destination before relying on provider dashboards for manual testing.

Keep examples realistic: include headers, event ids, timestamps, nested objects, and at least one duplicate delivery case. That makes payload fixtures useful for routing, idempotency, and replay tests instead of only proving that JSON parsing works.

Related guides