Webhooks

Webhooks are key to your payment integration game. They let Notch Pay holla at you 'bout any events goin' down on your account, like a payment that's lit or a transaction that's a flop.

Webhooks are a critical component of your payment integration system. They enable Notch Pay to promptly and automatically communicate important events on your account, such as a successful payment or a failed transaction.

More specifically, a webhook URL is an endpoint on your server that will receive these notifications. Whenever an event is triggered, a POST request will be made to this endpoint, carrying a JSON body that contains vital information about the event, including its type and associated data.

Structure of a webhook

All webhook payloads adhere to a consistent basic structure, encompassing three primary components.

• an event field describing the type of event
• an id containing the ID of the event
• a data object. The contents of this object will vary depending on the event, but typically it will contain details of the resources associated

Example

{
  "id": "whk.sdjdksjhkjsd",
  "event": "payment.complete",
  "data": {
    "amount": 5,
    "amount_total": 4,
    "sandbox": false,
    "fee": 1,
    "converted_amount": 5,
    "payment_method": "pm.nY9yqhuOoXVzmHJG",
    "customer": "cus.40jRRfanz7tKgZrl",
    "reference": "trx.khOZ3KT74j3gDeli5C3xV9Bu",
    "provider_reference": null,
    "status": "complete",
    "currency": "XAF",
    "geo": "129.0.189.24",
    "created_at": "2024-04-22T16:33:37.000000Z",
    "updated_at": "2024-04-22T16:34:19.000000Z"
  }
}

Types of events

Here are the current events we trigger, with more to be added as we expand our actions in the future:

Feel free to use these event names in your application to initiate specific actions whenever Notch Pay emits these events.

Enabling webhooks

To configure a webhook on your Notch Pay account, please follow these steps:

1. Log in to your dashboard, then click on Settings.
2. Proceed to the Webhooks section by clicking on Developer and add your webhook URL.

Implementing a webhook

Developing a webhook endpoint on your server is comparable to creating any other API endpoint with a POST route entry.

Security: Always verify webhook

When configuring webhooks, one has the ability to establish a secret hash. As webhook URLs are openly accessible, the secret hash enables validation of incoming requests, confirming they originated from Notch pay. While any value can be designated as the secret hash, it is recommended to use a random value and store it as an environment variable on the server.

To know for sure that a webhook was, in fact, sent by Notch Pay instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named x-notch-signature, and you can verify this signature by using your webhook hash key or your Notch Pay private key. The signature is an HMAC hash of your webhook hash or your private key. Here is an example of how to verify the signature in your app:

$signature = $request['headers']['x-notch-signature'];
$hash = hash('sha256', [YOUR_ID_OR_WEBHOOK_SECRET_HASH]);

if (hash_equals($hash, $signature)) {
  // Request is verified
} else {
  // Request could not be verified
}

If your generated signature matches the x-notch-signature header, you can be sure that the request was truly coming from Notch Pay. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Notch Pay.

Responding to webhook requests

To ensure successful acknowledgement of a webhook, it is imperative that your endpoint issues a 200 HTTP status code. All response codes other than 200, including 3xx codes, will be considered as a failure. It is notable that response body and headers are of no significance in this regard.

Best practices for Webhook

To confirm success, it is necessary for your webhook endpoint to respond within the given time limit. Any failure to do so will prompt a retry attempt. To circumvent timeout, it is advisable to refrain from long-running tasks or network calls in the webhook endpoint.

If feasible, it is recommended to have the webhook endpoint promptly return a 200 status code and then execute further duties; otherwise, it is crucial to dispatch long-running tasks to a job queue prior to responding.

Additionally, to avoid causing any erroneous outcomes for a customer, it is necessary to ensure that the event processing is idempotent, allowing for multiple webhook event calls with identical outcomes.