Webhooks Overview

Webhooks let your server react to events that happen out-of-band — most importantly, when a payment confirms on-chain. They are the reliable signal for fulfillment.

How it works

1. You register an endpoint URL via POST /v1/webhook_endpoints, specifying which events you want.
2. ParaSta returns a signing secret. Save it — it cannot be retrieved later.
3. When an event occurs, ParaSta POSTs a JSON payload to your URL with the X-ParaSta-Signature header.
4. You verify the signature, check event.id for idempotency, then process.

Always verify signatures

Never trust a webhook payload before verifying its X-ParaSta-Signature header — anyone with your endpoint URL can POST arbitrary JSON. See Verifying signatures.

Payload shape

{
  "id": "evt_abc123",
  "type": "checkout.session.completed",
  "created": "2026-05-06T10:32:01Z",
  "data": {
    "object": { /* the relevant object — Checkout Session, Payment, etc. */ }
  },
  "livemode": false
}

Best practices

• Respond 2xx within 10 seconds. ParaSta retries non-2xx responses.
• Be idempotent. Use event.id as a dedupe key — the same event may be delivered multiple times.
• Handle out-of-order delivery. Especially payment.pending and payment.succeeded — design your state machine to accept events in any order.

Process asynchronously

Acknowledge the webhook with a 2xx immediately, then enqueue the work for a background worker. This keeps you under the 10-second deadline even when downstream systems are slow.

See also

• Verifying signatures
• Event types
• Retries & Idempotency