Webhook Setup Primer

Webhooks notify your server when payments succeed, fail, or are refunded. Configure them early in technical onboarding so you can validate the complete payment flow on Fin staging before moving to production.

Why Webhooks Matter

Approach	Limitation
Redirect to `successUrl` only	The customer may close the browser before the redirect. A redirect is not proof of payment.
Polling the status API	Works, but may be slower and can miss asynchronous updates between polling requests.
Webhooks	Provide server-to-server notifications when supported transaction events occur.

❗️
Always confirm the final payment status using the Payment Status API or a webhook. Never rely on successUrl alone.

Minimum Requirements

Requirement	Detail
HTTPS URL	Use a publicly reachable HTTPS endpoint with a valid TLS certificate.
POST handler	Accept incoming `POST` requests with an `application/json` body.
Idempotency	The same event may be delivered more than once. Handle duplicate events safely and deduplicate using a suitable transaction or event identifier.
Fast response	Return an HTTP `200` response within 5 seconds whenever possible. Process intensive tasks asynchronously.
Logging	Log the received event, transaction reference, processing result, and any errors for troubleshooting.
Environment separation	Use separate webhook URLs or paths for Fin staging and production.

Conceptual Webhook Flow

sequenceDiagram
    participant Gateway as DigetPay Gateway
    participant Webhook as Merchant Webhook Endpoint
    participant Server as Merchant Backend
    participant Database as Merchant Database

    Gateway-->>Webhook: Send transaction event
    Webhook->>Webhook: Validate request and parse payload
    Webhook-->>Gateway: HTTP 200 acknowledgment
    Webhook->>Server: Process event asynchronously
    Server->>Database: Update transaction/order status
    Server->>Database: Ignore duplicate event if already processed

The diagram shows the recommended processing pattern. The exact event fields and status values depend on the webhook payload documented in the webhook event guide.

Setup Steps

Choose a webhook URL

Example:

https://yourstore.com/webhooks/digetpay
Implement the webhook handler

Review Handle Webhooks and the PHP examples in Hosted Checkout.
Register the webhook in the dashboard

Open Settings → Webhooks and add the endpoint.

For Fin staging, use the staging dashboard:

https://fin-admin.digetpay.com
Test the endpoint on Fin staging

Complete a test payment and verify that:
- The webhook request reaches your server.
- Your endpoint returns HTTP 200.
- The transaction and order status are updated correctly.
- Duplicate deliveries do not create duplicate orders, refunds, or other side effects.
Configure production

After successful staging validation, register the production webhook URL and test it with production credentials according to your go-live process.

Full Guides

Configure Webhooks

Webhook Security

Review the available webhook authenticity and validation requirements.

Webhook Event Payloads

Review payload fields, transaction references, and status mapping.

Handle Webhooks

Implement the server-side webhook receiver and process incoming events.

Staging vs Production

Environment	Recommended Configuration
Fin staging	Use staging API keys, staging webhook URLs, and test transactions only.
Production	Use production API keys, production webhook URLs, and live transaction processing.

Keep staging and production configurations separate to prevent test events from updating live orders or records.

Troubleshooting Checklist

If your webhook is not received or processed correctly, verify the following:

The URL is publicly reachable from the internet.
The endpoint uses HTTPS and has a valid TLS certificate.
The server accepts POST requests.
The endpoint accepts application/json.
The request is not blocked by a firewall, WAF, or IP restriction.
The endpoint returns HTTP 200 within the expected response time.
The transaction reference is logged correctly.
Duplicate events are handled safely.
The webhook is registered in the correct environment.
The endpoint is configured under the correct merchant account.

Important

A webhook is an asynchronous notification and should be processed safely. For critical order fulfillment, refunds, or other financial actions, follow the documented transaction verification process and use the Payment Status API when additional confirmation is required.