After verifying the signature, process the event asynchronously. Your endpoint must return 2xx within 30 seconds — PayGrid retries on failure or timeout.
Handler flow Recommended pattern:
Receive POST → verify signature on raw body → return 200 OK → process in background
Handler checklist
Verify the signature on the raw request body (not re-serialized JSON).
Return 2xx within 30 seconds — queue or background-task business logic.
Deduplicate webhooks by event_id; deduplicate callbacks by transaction_id.
Confirm data.amount, data.currency, and merchant_reference match your order.
Act on the event type (see below).
Deduplication Notification type Dedup key Notes Webhook event_idOne per status transition; stable across retries Callback transaction_idOne callback per payment
On retries, PayGrid re-sends the same payload with the same event_id, but X-MeetPay-Delivery-ID changes per attempt. Store processed event_id values and skip duplicates.
Validate the payment Before fulfilling an order:
Confirm transaction_id or merchant_reference maps to a real order in your system.
Match data.amount and data.currency (webhooks) or amount and currency (callbacks) to what you initiated.
Reject or flag mismatches — do not fulfill on amount/currency drift.
Actions by event Event Action webhook.testVerify signature only; return 200 — do not fulfill orders payment.completedFulfill order, mark paid, credit user payment.failedCancel order, release reserved stock, notify customer payment.expiredCancel order, release reserved stock payment.cancelledCancel order, release reserved stock payment.processingOptional: update UI to “processing” (rare for mobile)
Don’t assume an intermediate event will precede the terminal one. Only advance your internal order status forward — never backward.
Retries and polling fallback Scenario Behavior Your endpoint returns non-2xx or times out PayGrid retries automatically (up to 5 attempts per delivery) Retry delays ~30s → 2m → 10m → 1h between attempts HTTP client timeout PayGrid waits up to 30 seconds per delivery attempt for your response Retries exhausted Delivery is dead-lettered; PayGrid notifies you by email — recover via polling Missed webhook GET /api/v1/payments/{id} or POST /api/v1/payments/{id}/refresh
Design handlers to be idempotent — the same event_id may arrive more than once.
Track payments Polling, status values, and listing payments
Next step: Payload reference 
