Webhooks Overview

Webhooks are server-to-server notifications sent by HesabPay when payment events occur.

They are the recommended way to confirm payment status in your backend. Redirect URLs are useful for customer experience, but webhooks are more reliable for order updates, fulfillment, reconciliation, and automation.

Step-by-Step Flow

1. Understand Webhooks

HesabPay sends an HTTP POST request to your server when a payment event occurs.

Use webhooks to:

• Receive instant payment notifications.
• Update order status automatically.
• Trigger fulfillment after successful payment.
• Record failed payments.
• Keep your backend synchronized with payment status.

2. Register Your Webhook URL

Register your webhook endpoint in the dashboard so HesabPay knows where to send payment events.

The webhook URL must be a publicly accessible endpoint on your server, for example:

https://merchant.example.com/webhooks/hesabpay

For production, use HTTPS.

3. Create a Webhook Endpoint

Create an endpoint in your backend that accepts POST requests and reads JSON payloads.

Your endpoint should:

• Accept POST requests.
• Parse the JSON body.
• Extract signature and timestamp.
• Check whether the request came from a trusted source by verifying the webhook signature.
• Verify the webhook signature.
• Process the event only after verification succeeds.
• Return HTTP 200 after successful processing.

Do not update orders, invoices, or balances until the signature verification succeeds. If verification fails, reject the request and treat it as untrusted.

4. Verify Webhook Signature

Always verify webhook signatures before trusting the payload.

The webhook payload includes:

• signature
• timestamp

Send those values to the signature verification endpoint before updating your order or transaction state.

5. Handle Payment Events

After verification, process the event based on the payment status.

For successful payments, update your internal order or invoice as paid. For failed payments, keep the order unpaid and show the customer a failure or retry state.

Webhook handling should be idempotent. If the same event is received more than once, your system should not fulfill the same order twice.

Supported Events

Event	Description
payment_success	Sent when a payment is completed successfully.
payment_failure	Sent when a payment fails or is declined.

Register Webhooks in Dashboard

1. Sign in to the dashboard.
2. Open the Developer section from the sidebar.
3. Open the Webhooks section.
4. Click Add Webhook or the equivalent add action.
5. Enter your webhook URL.
6. Select the event type:
   • payment_success
   • payment_failure
7. Add an optional description, such as Order completion notifications.
8. Save the webhook.

After registration, complete a test payment and check your server logs to confirm that your endpoint receives the webhook.

Manage Registered Webhooks

From the dashboard, you can:

• View registered webhook endpoints.
• Edit endpoint URLs and descriptions.
• Delete endpoints you no longer use.
• Register separate URLs for different event types.

Next Steps

• Review Event Payloads to understand the data HesabPay sends.
• Review Verify Signatures before processing events in production.