Webhooks

What are Webhooks?

Webhooks allow your application to receive automatic notifications when a payment is completed successfully. Instead of constantly checking payment status via API calls, HexPay will send an HTTP POST request to your server with payment details.

How Webhooks Work

When creating a payment, specify a webhookURL parameter. Once the payment status changes to SUCCESSFUL, HexPay will automatically send a POST request to your specified URL.

Create Payment via API

Learn how to include webhookURL when creating payments

Webhook Payload

When a payment is completed, HexPay sends a POST request with this JSON payload:

{
  "paymentID": "0199ea7a-0e5f-7545-9885-a0c22e99060f",
  "paymentMetadata": "eyJvcmRlcklkIjoiMTIzNDUifQ=="
}

Payload Fields:

paymentID - Unique identifier of the completed payment
paymentMetadata - Custom data that you provided in the metadata field when creating the payment. This can contain any information you need to identify or process the payment (order ID, customer details, etc.)

Guaranteed Delivery

Automatic Retry Mechanism

HexPay guarantees webhook delivery through automatic retries. If your endpoint doesn't respond with HTTP status code 200, HexPay will continue retrying the webhook delivery until it receives a successful response.

Key points:

Webhooks are retried automatically with increasing delays
Retries continue until your server returns status 200
This ensures you never miss payment notifications

Requirements

Your webhook endpoint must:

Return HTTP status 200 when the webhook is successfully received
Respond within 30 seconds to avoid timeouts
Handle duplicate deliveries - the same webhook may be sent multiple times due to retries

Security: Use HTTPS

Always Use HTTPS

For security and reliability, always use HTTPS URLs for your webhooks:

✅ Correct: https://yoursite.com/webhook
❌ Avoid:   http://yoursite.com/webhook

Why HTTPS is important:

Data encryption in transit
Authentication verification
Industry standard for API communications
Many platforms block HTTP webhooks

Next Steps

Monitor Payment Status

Use the payment ID to track payment details and status via API