How webhooks work

How spuke delivers webhooks, retries, and how to configure endpoints.

How webhooks work

Webhooks let spuke notify your server whenever something happens on your account — a payment succeeds, an invoice is paid, a dispute is opened.

Configure endpoints

Dashboard → Developers → Webhooks → Add endpoint

  • url — must be HTTPS.
  • description — free-form.
  • enabled_events — pick the events you want. Use * for everything.
  • mode — test or live. Test-mode endpoints only receive events from test keys.

On save spuke returns a signing secret (whsec_…) — copy it now, it's shown only once.

Delivery guarantees

  • HTTP POST with Content-Type: application/json.
  • 2xx = success. Any non-2xx (or timeout > 20 s) triggers exponential backoff retries for up to 72 hours (roughly 15 attempts).
  • Delivery attempts are visible per-event under the endpoint.
  • Events can arrive out of order. Use data.id + type for idempotency.

Envelope

{
  "id": "evt_01H…",
  "object": "event",
  "type": "checkout.session.completed",
  "created": 1735689600,
  "livemode": true,
  "data": {
    "object": { /* the resource — checkout session, invoice, charge, dispute, payout, … */ }
  }
}

The resource always lives at data.object. See Event reference for the exact shape per event type.

Testing

  • Use sk_test_… keys and a test-mode endpoint. spuke test cards work end-to-end.
  • The Developers → Webhooks → Test button sends a synthetic ping.test event.