Webhooks

Plaidly sends HTTP POST requests to your merchant webhook_url when a payment session changes state.

Events

Payload structure

{
  "event_type": "payment_session.completed",
  "session_id": "sess_01HX9K...",
  "status": "completed",
  "amount": 10,
  "currency": "USDC",
  "chain": "solana",
  "network": "mainnet",
  "timestamp": "1700000000"
}

Signature verification

Every webhook request includes an X-Plaidly-Signature header of the form t=<unix_seconds>,v1=<hex>, where v1 is HMAC-SHA256(webhook_secret, "<t>.<rawBody>") and the tolerance window is 5 minutes. Always verify this before processing. See HMAC verification for the full algorithm.

Retry policy

Delivery happens synchronously in the event pipeline with a short, bounded backoff — this is not a background queue with hours-long delays:

After 5 failed attempts the delivery is marked failed on the session's webhook delivery state. Trigger a manual redelivery with:

curl -X POST https://api.plaidly.io/v1/payment_sessions/<SESSION_ID>/webhook/retry \
  -H "X-API-Key: your_api_key"

See Webhook delivery status for how to inspect delivery attempts, status, and latency for a session.

Responding to webhooks

Return 200 OK promptly. Perform long-running work asynchronously — queue the event and return immediately; slow responses count against the attempt's latency but do not extend the retry schedule above.

Testing webhooks locally

Point webhook_url (set at registration, see Configure a webhook) at a local tunnel such as ngrok or localtunnel:

ngrok http 3000

Then register or re-register your sandbox merchant with the resulting HTTPS URL as webhook_url. You can also trigger deliveries on demand with the sandbox simulate endpoint instead of waiting for a real payment.

A plaidly listen --forward-to CLI command for local webhook forwarding is planned as part of the Plaidly CLI (BDT-544) and does not exist yet — use a tunnel tool until it ships.

Security checklist

• Verify X-Plaidly-Signature on every request
• Use HTTPS endpoints only
• Respond promptly (do not block on downstream work)
• Handle duplicate deliveries idempotently (same session_id + event_type may arrive more than once, including after a manual /webhook/retry call)