Introduction

Paysquad sends webhook events to your server to notify you of Paysquad lifecycle changes.

Events

Endpoint configuration

You can configure webhook endpoints in two ways:

1. Merchant Portal endpoints. Set up under Developer → Webhooks in the Merchant Portal. You can create multiple endpoints, each subscribed to a different combination of events, configured separately for Sandbox and Production. Use this for server-side integrations that handle events centrally.
2. Per-Paysquad paymentCompleteWebhook. Set at creation time on the Create Paysquad request. If supplied, all three events for that Paysquad are sent to this URL instead of any Portal-configured endpoints.

The per-Paysquad URL takes precedence over Portal endpoints. Events are not duplicated to both.

Request shape

Every webhook is an HTTP POST with:

• Body: JSON payload (see event reference pages).
• Header X-Paysquad-Signature: HMAC SHA-256 signature of the raw body. Verify this on every request; see the Validating Webhook Authenticity page.
• Header X-Paysquad-Environment: Production, Sandbox, or Beta. Use this to select the correct signing key.

Expected response

Return HTTP 200 within 10 seconds to acknowledge receipt. Any other status (or a timeout) is treated as a failure.

Delivery order

Paysquad does not guarantee the order in which webhook events are delivered. Always treat each event independently and fetch the current Paysquad state via GET /api/merchant/paysquad/{id} before acting.

Retry behaviour

If your endpoint returns a non-2xx response or times out, Paysquad retries up to 2 more times (3 attempts total) with a minimum 15-minute gap between attempts. After that, the event is marked as failed and is not retried automatically. You can also trigger a manual retry from the Merchant Portal under Developer → Webhooks. Missed events can be reconciled by calling GET /api/merchant/paysquad/{id}.

Best practices

• Always verify the signature before acting on a webhook. See the Validating Webhook Authenticity page.
• Respond quickly. Acknowledge the webhook first, then process asynchronously on your side.
• Be idempotent. A retry may deliver an event you've already handled. Key off paySquadId plus eventName.
• Fetch the Paysquad to confirm. Webhooks carry only the event type and paySquadId. For any business-logic decisions, call GET /api/merchant/paysquad/{id} to get the authoritative state.
• Reconcile daily. Even with retries, an outage on your side can drop an event. A simple nightly reconciliation job against GET closes the gap.