Webhooks Configuration

Overview

Cleeng webhooks are real-time HTTP POST requests sent to the endpoint(s) you provide, so your systems can be informed by Cleeng when specific events happen in the platform. This page walks you through:

• configuring webhook subscriptions,
• verifying which topics you’re subscribed to, and
• what retry policy is and how to set up webhook delivery retries.

How to configure webhooks

• Make an API call to the Webhook settings endpoint (PUT /3.1/webhook_subscriptions/{topic}).

• Replace {topic} with the topic you want to subscribe to (i.e. the event you want to be notified about), for example subscriptionReadyForPaymentAuthorisation. A topic identifies what event has occurred in the Cleeng system.

  See the related sections for the available webhook topics.

• Provide a list of endpoints to which notifications should be delivered.

• (Optional) Apply the webhook filtering logic - filtering by paymentMethodId. This allows you to differentiate transactions coming from the respective connectors.

• (Recommended) Enable webhook verification. It is optional, but we recommend enabling it for security purposes.

NOTE: You have to repeat the configuration steps for each required topic.

🚧

Warning

Be careful not to override the webhooks you have already subscribed to (see the example for more details).

The PUT method creates a new resource or replaces a representation of the target resource with the request message payload.

Example

See the example scenario:

1. You want to set up recurring payments for a custom payment connector 1. You need to subscribe to all required topics, one by one.

   You need to repeat it for each required webhook topic.

2. After you’ve done it, you may decide to also set up recurring payments for another custom payment connector. Then, you also need to subscribe to all required topics, one by one. Let’s say you decide that you also want to subscribe to the same webhook topic as for the custom payment connector 1. This is what you need to do to subscribe to subscriptionReadyForPaymentAuthorisation:

When subscribing custom payment connector 2 to a webhook topic, make sure its configuration does not override the existing webhook subscriptions for custom payment connector 1. To do this correctly, include the existing subscription for custom payment connector 1 and add custom payment connector 2 in the same PUT request so that both connectors remain subscribed.

PUT 'https://api.sandbox.cleeng.com/3.1/webhook_subscriptions/subscriptionReadyForPaymentAuthorisation' \
[
    {
        "url": "https://connector1.example.com/authorise-payment",
        "filters": [
            {
                "name": "paymentMethodId",
                "options": {
                    "value": $connector1PaymentMethodId
                }
            }
        ]
    },

    {
        "url": "https://connector2.example.com/authorise-payment",
        "filters": [
            {
                "name": "paymentMethodId",
                "options": {
                    "value": $connector2PaymentMethodId
                }
            }
        ]
    },

]

Response 200 - OK:

{
  "success": true,
  "data": [
    {
      "topic": "subscriptionReadyForPaymentAuthorisation",
      "endpoints": [
        {
          "url": "https://connector1.example.com/authorise-payment",
          "filters": [
            {
              "name": "paymentMethodId",
              "options": {
                "value": 451494717
              }
            }
          ],
          "verification": null
        },
        {
          "url": "https://connector2.example.com/authorise-payment",
          "filters": [
            {
              "name": "paymentMethodId",
              "options": {
                "value": 123456789
              }
            }
          ],
          "verification": null
        }
      ]
    }
  ],
  "message": "Successfully subscribed to webhook"
}

If you want to add another connector, you need to repeat the previous two.

Check webhook topics you subscribed to

You can check the topics you subscribed to with the List webhook subscriptions endpoint (GET /3.1/webhook_subscriptions).

Configure Webhook Retries

To improve delivery reliability, you can configure your webhook endpoints to automatically retry delivery in the event of a transient failure (such as a 5xx error, timeout, or network issue). This section will guide you through enabling and managing this feature.

When enabled, failed deliveries are automatically retried up to a specified number of times using an exponential backoff strategy. This approach increases the delay between each subsequent attempt, giving your consumer's server time to recover.

The retry schedule is as follows:

Enable the Retry Policy

To enable retries, add the retryPolicy object to your webhook endpoint configuration.

{
 "retryPolicy": {  
    "enabled": true,  
    "maxAttempts": 4
 }
}

• enabled: Set to true to activate the retry mechanism.
• maxAttempts: Specify the total number of delivery attempts (1 initial + 3 retries in the example above). Maximum number: 4.

If the retryPolicy object is not included in your configuration, the endpoint will default to the standard single-delivery attempt.

Ensure Idempotent Processing

A retried request can sometimes result in the same event being delivered more than once. To prevent duplicate processing, your endpoint must be idempotent.

All webhook deliveries now include headers to help you handle potential duplicates:

Best Practice

When enabling retries, you should implement idempotency using the X-Webhook-Delivery-Id header, as duplicate deliveries may occur if an endpoint returns 5xx but still processes the request.

A delivery is considered permanently failed if it exhausts all retry attempts or if your endpoint returns a 4xx status code.

Example of Webhook Retries Configuration

See the example for PUT https://api.sandbox.cleeng.com/3.1/webhook_subscriptions/customerRegistered:

[
    {
        "url": "https:/test.example.com/webhook-handler/customer-registered",
        "retryPolicy": {  
            "enabled": true,  
            "maxAttempts": 4
        }
    }
]