Webhooks Overview

Webhooks are used so your server can receive real-time notifications from Gerbang Pay when there is a change in payment status (e.g., the customer has transferred funds, or the bill's time limit has expired).

Instead of having to periodically poll the GET /v1/payments/{id} API, webhooks ensure your application gets immediate updates (a push mechanism).

Why are Gerbang Pay Webhooks Different?

If you were to integrate Winpay and Midtrans directly, you would have to handle various webhook formats and completely different signature mechanisms.

With Gerbang Pay, we simplify this process. Our system will:

1. Receive callbacks from the providers (Midtrans/Winpay)
2. Verify each provider's signature internally
3. Save the raw callback logs
4. Transform the payload shape into the Gerbang Pay Universal Webhook format
5. Re-sign the payload using HMAC-SHA256 (with your webhook_secret)
6. Send it to your server's callback_url

When are Webhooks Sent?

Webhooks are only sent for asynchronous state changes. Gerbang Pay DOES NOT send webhooks for the payment.created event. This is because the bill creation information is already obtained directly (synchronously) when you call the POST /v1/payments/create API.

Events that will trigger a webhook:

• payment.paid
• payment.failed
• payment.expired
• payment.cancelled
• payment.challenged
• (And refund-related events if any)

See the Webhook Events List page for details on the body structure of each event.

HTTP Headers in Webhooks

Every webhook POST request from Gerbang Pay to your server will always include the following headers:

Header	Explanation
Content-Type	Always application/json
X-Gerbang-Event-Id	A unique UUID representing one delivery of this event (useful for preventing double processing / receiver idempotency).
X-Gerbang-Event-Type	The type of event, for example payment.paid.
X-Gerbang-Signature	Contains the HMAC-SHA256 signature of the payload for security validation purposes. Format: sha256={hmac_hex}.

Retry Mechanism

If your server fails to respond to a webhook (returns an HTTP status other than 2xx or times out), Gerbang Pay will automatically attempt to resend the webhook.

• Maximum Retries: 3 retries (total 4 attempts)
• Interval: 10-second pause between attempts (using a RabbitMQ Dead Letter Exchange / DLX mechanism)

If your server still fails (or is slow) to respond after 3 retries, the message processing will be stopped and marked as a permanent failure in our logs.

💡 Best Practice: Immediately return a 200 OK status shortly after your server receives a webhook. Move heavy business processes (like updating the database, sending emails to customers) to a background worker in your system (queue) so it doesn't cause a webhook connection timeout.

Webhook URL Configuration

1. Log in to the Gerbang Pay Dashboard
2. Go to Integration Setup
3. Enter your server's endpoint in the Callback / Webhook URL field. (Example: https://api.your-store.com/webhook/gerbang-pay)
4. Copy the Webhook Secret value generated by the system. You will use it to verify the signature.