Consuming webhooks

Automate your order management with real-time notifications

N-Genius Online Online supports webhooks — secure server-to-server notifications that alert your systems the moment something important happens with an order. This lets you automatically update your backend, notify customers, and eliminate the need for manual reconciliation or polling logic.

Introduction

What Are Webhooks?

Webhooks are server-to-server notifications sent by N-Genius Online when key events occur on an order — such as a successful payment, a failed capture, or a refund.

By listening for these real-time events, your systems can automatically react without polling, making your integration more efficient and responsive.

Whether you're using the Hosted Payment Page, creating orders via API, or issuing invoices from the portal, webhooks can keep your backend in sync with payment activity.

Why Use Webhooks?

Webhooks help you:

  • Get notified when a payment succeeds — even if the customer doesn't return to your site.
  • Monitor the status of invoices created manually or via API.
  • Automate downstream processes like order fulfilment, notifications, and reporting.
  • Eliminate the need for polling endpoints or checking the dashboard manually.

How Webhooks Work in N-Genius Online

The diagram shows how webhooks work on the N-Genius platform.  It's for developers.

A webhook manages the workflow from customer payment to response.

When webhooks are enabled for your account, N-Genius Online will send an HTTP POST request to your configured endpoint every time a supported event occurs. The payload contains details about the order and the event type.

⚠️

N-Genius Online sends a single webhook per event — there are no retries if your server is unavailable or does not respond.

Delivery Behaviour

  • You will receive one POST request per event.
  • Events may be sent in quick succession (e.g. AUTHORISED followed by CAPTURED).
  • You must respond with HTTP status code 200 or 201 within 15 seconds to acknowledge receipt.

Configuring Webhooks

You can create and manage webhooks in the N-Genius Online portal:

  1. Log in to your merchant dashboard.
  2. Navigate to Settings > Integrations > Webhooks.
  3. Click New to create a new webhook.
The screenshot shows a step by step guide of setting up webhooks from within the N-Genius online portal

Configuring webhooks: A step-by-step guide.

Fill in the following fields:

FieldDescription
NameA friendly name to identify your webhook (e.g. Payment Events Handler)
URLThe HTTPS endpoint on your server to receive event data
Header Key (optional)A custom header name (e.g. X-Webhook-Token) for additional security
Header Value (optional)The expected value for the header key above

Once submitted, your webhook URL will be reviewed and whitelisted before it becomes active.

📘

Webhooks require whitelisting

After creating a webhook, our team will validate and approve your endpoint. Once approved, you will begin receiving event notifications.


Supported Webhook Events

Here is a list of events that can trigger a webhook:

EventDescription
AUTHORISEDTriggered when a payment has been authorized
DECLINEDTriggered when the authorization for a payment has been declined by the card-holder's issuing bank
APM_PAYMENT_ACCEPTEDThis event is triggered when we get a success response from the APM system for a payment.
AUTHORISATION_FAILEDTriggered when the authorization process has failed
FULL_AUTH_REVERSEDTriggered when an authorization has been reversed, either automatically following a post-authorization fraud screening rejection, or manually following an API or portal-based request to reverse the authorization.
FULL_AUTH_REVERSAL_FAILEDTriggered when a request to reverse an authorization has failed. Note that, in this circumstance, the payment will remain in an AUTHORISED state.
PURCHASEDTriggered when the PURCHASE process has succeeded.
PURCHASE_DECLINEDTriggered when the PURCHASE process has been declined.
PURCHASE_FAILEDTriggered when the PURCHASE process has failed.
PURCHASE_REVERSEDTriggered when a previous PURCHASE has been reversed either through the N-Genius Online portal, or using the APIs.
PURCHASE_REVERSAL_FAILEDTriggered when the request above to reverse a PURCHASE request has failed.
CAPTUREDTriggered when an AUTHORISED payment has been CAPTURED, in full.
CAPTURE_FAILEDTriggered when the CAPTURE process has failed.
CAPTURE_VOIDEDTriggered when a previous CAPTURE has been cancelled/voided either through the N-Genius Online portal, or using the APIs. Note that the payment will then return to an AUTHORISED state.
CAPTURE_VOID_FAILEDTriggered when the request above to cancel/void a CAPTURE request has failed.
CANCELLATION_REQUESTEDThis event is triggered when we cancel the APM payment.
CANCELLATION_FAILEDWhen APM system, declines or fail for a payment, the event has been triggered
CANCELLEDOn success of a payment cancellation from the APM system, the event is triggered
ORDER_CLOSEDTriggered when the order is marked as closed. This typically occurs when no further transactions (like captures or refunds) can be performed against it.
PARTIALLY_CAPTUREDTriggered when an AUTHORISED payment has been partially captured (i.e. for any value that does not meet or exceed the original authorization amount).
PARTIAL_CAPTURE_FAILEDTriggered when a request to CAPTURE an AUTHORISED payment has failed.
REFUNDEDTriggered when a CAPTURED payment has subsequently been refunded.
REFUND_FAILEDTriggered when a REFUND request has failed.
PARTIALLY_REFUNDEDTriggered when a CAPTURED payment has been partially refunded (i.e. refunded for an amount less than the original CAPTURE request).
REFUND_REQUESTEDWhen we request refund for a transaction to APM system, this event is triggered
REFUND_REQUEST_FAILEDOn request to APM system for refund, if it fails the event is triggered
PARTIAL_REFUND_FAILEDTriggered when a PARTIAL_REFUND request has failed.
PARTIAL_REFUND_REQUEST_FAILEDOn request to APM system for partial refund, if it fails the event is triggered
PARTIAL_REFUND_REQUESTEDWhen we request partial refund for a transaction to APM system, this event is triggered
REFUND_VOIDEDTriggered when a REFUND has been cancelled/voided.
REFUND_VOID_FAILEDTriggered when a request to cancel/void a REFUND request has failed.
REFUND_VOID_REQUESTEDWhen cancel refund is requested to the APM system, this event is triggered
GATEWAY_RISK_PRE_AUTH_REJECTEDTriggered when a payment has been rejected by the N-Genius Online pre-authorization risk rules service.
PRE_AUTH_FRAUD_CHECK_REJECTEDTriggered when a payment has been rejected by a 3rd party pre-authorization fraud screening service.
POST_AUTH_FRAUD_CHECK_REJECTEDTriggered when a payment has been rejected by a 3rd party post-authorization fraud screening service.
POST_AUTH_FRAUD_CHECK_REVIEWWhen post auth check is pending, this event is triggered
POST_AUTH_FRAUD_CHECK_ACCEPTEDWhen post auth check is success, this event is triggered
ORDER

🌀

You may receive multiple events for a single order. Ensure your application handles them idempotently.

Handling Webhooks and Sample Payloads

Receiving a Webhook

When your endpoint receives a webhook request from N-Genius Online:

  1. Read the request body — it's in JSON format and contains the event details.
  2. Verify the event — check the event type and ensure it’s one your system can handle.
  3. Respond quickly — return an HTTP 200 or 201 status code within 15 seconds to acknowledge successful receipt.

Here’s a sample webhook payload:

{
  "event": "CAPTURED",
  "order": {
    "reference": "ORD-123456",
    "id": "abc123xyz",
    "amount": {
      "currencyCode": "AED",
      "value": 10000
    }
  },
  "transaction": {
    "id": "txn789",
    "state": "CAPTURED",
    "date": "2024-12-01T13:22:45Z"
  },
  "timestamp": "2024-12-01T13:22:45Z"
}

⚠️

Webhook payloads are not signed. If you're concerned about security, use a secret header (configured in the portal) to validate that the request is coming from N-Genius Online.

Testing Webhooks

Currently, webhook simulation is not supported from the dashboard. We recommend:

  • Triggering real transactions in a sandbox environment.
  • Using tools like Webhook.site to inspect incoming requests during development.

Best Practices

  • Make your webhook handler idempotent
    Each event should only be processed once, even if accidentally triggered again.
  • Respond quickly
    Always reply with a 200 or 201 status code within 15 seconds — even if internal processing takes longer.
  • Log everything
    Store logs of all received events and responses for easier debugging and auditing.
  • Use secret headers
    Add a custom header and value to your webhook config to verify requests originate from N-Genius Online.
  • Handle unknown events gracefully
    Don’t crash your app if you receive a new event type — log and skip it.

Common Pitfalls

  • Assuming a single event: A single payment might trigger multiple events (AUTHORISED, CAPTURED, etc.).
  • Expecting retries: N-Genius Online does not retry failed webhooks. If your server is down, the event is lost.
  • Failing to validate payloads: Don’t trust the request blindly — always verify it.
  • Delaying responses: Avoid long processing before sending an HTTP 200. Acknowledge first, process after.