Skip to main content
Payment events, payloads, and how to handle them securely.
Bleepay sends HTTP POST requests to your registered webhook endpoints when payment-related events occur. Use these to update your order state and fulfill orders.

​
Endpoint requirements

  • URL: The webhook URL you register for your business.
  • Method: POST
  • Content-Type: application/json
  • Signature: HMAC-SHA256 in the X-Platform-Signature header. Verify this to ensure the request came from Bleepay.
  • Response: Return 200 OK quickly so Bleepay can consider the delivery successful. Process asynchronously if needed.

​
Event types

EventWhen it fires
deposit.createdA deposit session has been created.
deposit.pendingAn on-chain transaction has been detected and is awaiting confirmations.
deposit.confirmedThe transaction has received the required block confirmations. Use this to fulfill.
deposit.expiredThe deposit session expired without receiving funds (30-minute window).
deposit.underpaidThe customer sent less than the required amount.
deposit.overpaidThe customer sent more than the required amount.
Always check the type field and handle idempotency (e.g. by order_id or tx_id).

​
Example payload

{
    "id": "evt_abc123",
    "type": "deposit.confirmed",
    "data": {
        "sessionId": "dep_xyz789",
        "orderId": "ORDER-5678",
        "status": "CONFIRMED",
        "amount": "100.00",
        "currency": "EURC",
        "network": "polygon",
        "txHash": "0xTransactionHash",
        "depositAddress": "0xDepositAddress",
        "customerEmail": "customer@example.com",
        "customerReference": "ref_123",
        "metadata": {}
    }
}

​
Best practices

  1. Verify signatures: Always validate the X-Platform-Signature header using your webhook signing secret to ensure the payload originated from Bleepay.
  2. Idempotency: Process each event by its id so duplicate deliveries don’t double-fulfill.
  3. Async processing: Acknowledge with 200 quickly; do heavy work (DB, external APIs) in a background job.
  4. Retries: Bleepay retries failed deliveries up to 3 times at 30-second intervals. Your handler must remain idempotent.

​
Setting up webhooks

Webhook endpoints are configured per business in the dashboard:
  1. Register an endpoint URL.
  2. Select which event types to subscribe to (e.g. deposit.confirmed, deposit.expired).
  3. Store the signing secret returned at creation time — it is shown only once.
  4. Use the secret to verify the X-Platform-Signature header on incoming requests.

​
Next steps