Webhooks Configuration

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).