> ## Documentation Index
> Fetch the complete documentation index at: https://docs.klyme.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Notifications

> How to receive webhook notifications for events

Webhook notifications are automated messages sent from Klyme to a specific URL endpoint of your choice.

Instead of constantly checking for updates (polling) via API, webhooks push real-time data to a designated URL endpoint as soon as an event occurs such as a
payment status changing from `PENDING` to `COMPLETED`.

### Key Points

* Webhook notifications are encrypted using **aes-256-ctr**.
* Encyption for webhook notifications is enabled by default. However, encryption can be disabled upon request.
* A `HTTP 200 response` **must** be sent back from the client to mark the delivery of the webhook notification as successful.
* You have 5 attempts to successfully receive a unique webhook notification and send back a `HTTP 200 response`.
* If after 5 attempts a `HTTP 200 response` is not sent back, the notification will stop sending as a failsafe.
* Unreceived webhook notifications are still recorded by Klyme and can be re-sent upon request.

## How to decrypt webhook notifications

<CodeGroup>
  ```javascript JavaScript lines icon="square-js" theme={null}
  const express = require('express');
  const crypto = require('crypto');
  const app = express();

  app.use(express.json());

  app.post('/webhooks', (req, res) => {
      const iv = Buffer.from(req.body.iv, 'hex');
      let encryptedText = Buffer.from(req.body.data, 'hex');
      let decipher = crypto.createDecipheriv('aes-256-ctr', Buffer.from(process.env.WEBHOOK_SECRET), iv);
      let decrypted = decipher.update(encryptedText);
      decrypted = Buffer.concat([decrypted, decipher.final()]);

      res.status(200).send();
  });
  ```

  ```php PHP lines icon="php" theme={null}
  $secret = getenv('WEBHOOK_SECRET');

  if ($_SERVER['REQUEST_METHOD'] === 'POST' && $_SERVER['REQUEST_URI'] === '/webhooks') {
      $iv = hex2bin($_POST['iv']);
      $encryptedText = hex2bin($_POST['data']);

      // Decrypt the data
      $decrypted = openssl_decrypt($encryptedText, 'aes-256-ctr', $secret, OPENSSL_RAW_DATA, $iv);

      if ($decrypted === false) {
          // Handle decryption error
          http_response_code(400);
          echo 'Decryption failed';
          exit;
      }

      // Send a 200 OK response
      http_response_code(200);
      echo 'OK';
  } else {
      // Handle other requests
      http_response_code(404);
      echo 'Not Found';
  }
  ```

  ```javascript Payload theme={null}
  {
      "processingTime": "2025-07-23 18:32:26",
      "uuid": "ce1797873467e1bbddda9f99c42f126a",
      "merchantUuid": "xfe3539cb23ad9731be57905b8a0c099",
      "amount": 10.00,
      "currency": "GBP",
      "reference": "1A2B3C4D",
      "result": {
          "status": 1,
          "statusCode": "ACCC",
          "description": "COMPLETED",
          "institution": "monzo_ob",
          "redirectUrl": "https://your-redirect-url.com"
      },
      "customer": {
          "firstName": null,
          "surname": null,
          "middleName": null,
          "email": "info@klyme.io",
          "mobile": null,
          "phone": null,
          "customerId": null,
          "dob": null,
          "gender": null,
          "address1": null,
          "address2": null,
          "city": "Manchester",
          "postcode": null,
          "country": "GB",
          "company": null,
          "ip": "16.126.433.250",
          "payerName": null,
          "payerIban": null,
          "payerAccNum": null,
          "payerSortCode": null
      },
      "cart": {
          "items": [],
          "affiliateId": null,
          "discountCode": null
      },
      "device": {
          "deviceOs": "iOS",
          "deviceOsVersion": "18.5",
          "deviceName": "iPhone",
          "deviceBrowser": "Mobile Safari",
          "deviceBrowserVersion": "18.5"
          "deviceToken": "nTW220MaiBjonNLoox2k",
          "deviceIsMobile": 1,
      },
      "customParameters": {
          "custom1": null,
          "custom2": null,
          "custom3": null,
          "custom4": null,
          "custom5": null,
          "customJson": null
      }
  }
  ```
</CodeGroup>