Handle Webhook Events

Learn how to receive and process webhook events from Plexy.

Webhook payload structure

Every webhook event has a consistent structure:

{
  "id": "evt_1234567890",
  "type": "payment.succeeded",
  "created": 1679529600,
  "data": {
    "id": "pay_abc123",
    "amount": 5000,
    "currency": "USD",
    "status": "succeeded"
  }
}

Basic webhook handler

Plexy delivers events by sending an HTTP POST to your endpoint. For example, a payment.succeeded event arrives as:

curl -X POST https://your-app.example.com/webhooks/plexy \
  -H "Plexy-Signature: t=1716640000,v1=ab12cd34ef5678..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "evt_1234567890",
    "type": "payment.succeeded",
    "created": 1716640000,
    "data": {
      "id": "pay_abc123",
      "amount": 5000,
      "currency": "USD",
      "status": "succeeded"
    }
  }'

Verify the signature

Compute HMAC-SHA256(<raw request body>, <your webhook secret>), hex-encode the result, and compare against the v1= value in the Plexy-Signature header using a constant-time comparison. Reject the request if they differ.

Your endpoint should handle at minimum: payment.succeeded, payment.failed, and refund.succeeded. Respond with HTTP 200 to acknowledge receipt.

Best practices

Return quickly

Acknowledge receipt immediately and process the event asynchronously. Plexy considers a webhook delivery failed if your endpoint does not respond within 30 seconds. Return a 200 status as soon as the request is received, then process it in a background task or queue.

Handle duplicates

Events may be delivered more than once. Use the event id to ensure idempotency:

{
  "id": "evt_1234567890",
  "type": "payment.succeeded"
}

Before processing, check whether you have already handled an event with that id. If so, skip processing and return 200. Record the id after successful processing so future duplicate deliveries are ignored.

Log all events

Log every incoming webhook payload — including the event id, type, timestamp, and raw body — for debugging and auditing. Store these logs for at least 30 days so you can correlate Plexy Dashboard delivery records with your application's processing history.

See also

• Webhook Types - All available events
• Secure Webhooks - Verify signatures
• Troubleshoot - Debug delivery issues