Set up and Use a Webhook

We recommend that you use the sandbox environment for accessing the Tenant portal, if you are trying to set up a Webhook for the first time.

Webhook notifications might not transport all the information you need. Their intent is only to notify the customer that something has changed. Make a call to APIs to receive more information about the event.

While there are multiple ways to receive notifications, the most tedious of them all is to constantly ask someone to send notifications. To alleviate this problem, Duck Creek Payments Orchestrator uses Webhooks to send notifications to you only when an event is processed. That way, you won't have to spend your precious resources to check the status with us but at the same time receive near real-time notifications of the event processed by Payments Orchestrator.

Before you Start

Before you start following this guide, you should understand the concepts related to the Payments Orchestrator application. You should also have access to the Tenant Portal and permission to set up Webhooks.

How it works?

When you set up and configure a Webhook, you will receive a verification key.
Whenever an event is processed within the Payments Orchestrator application, it will send event-related webhook payloads to the HTTPS destination that you specified in the setup.
You can then consume the payload directly or verify the payload before consuming it.
Finally, you will send an acknowledgement message back to the Payments Orchestrator application in the form of an HTTP status code.

How to Set Up Webhooks?

Login to the Tenant Portal.
Select Webhooks under Developers menu from the left sidebar. The Webhooks page appears with a list of all the created Theme templates (if any).
Click the button on the top-right corner of the page. The Add webhook page appears.
Fill the available fields with relevant information. Refer to the table below for more information on each fields.

Field	Description
Destination	Enter the full URL to an endpoint that Payments Orchestrator should post notifications to. Only HTTPS enabled URL are supported. For early testing purposes it is recommended to use an online tool such as HookBin to explore how messages are signed and delivered.
Events	Select one or more events whose payloads you should receive through this Webhook. Payments Orchestrator supports the following event types. `CHARGEBACK` notifies you if a chargeback's state changes. `CUSTOMER` notifies you if the customer's state changes. `FINANCIAL_INSTRUMENT` notifies you if a financial instrument's state changes. `INSTRUCTION` notifies you if an Instruction's state changes. `MANDATE` notifies you if a Mandate's (SEPA) state changes. `MANDATE_V2` notifies you if a Mandate's (SEPA and BACS) state changes. `ORDER` notifies you if an Order's state changes. `REFUND` notifies you if a Refund's state changes. `TRANSACTION` notifies you if a Transaction's state changes. `WHITELABEL_SESSION_EXPIRED` notifies you if a Whitelabel session has expired.
Maximum Batch Size	Enter the maximum number of events that should be rolled up into a batch before the payload is dispatched to the destination.
Maximum Batch Time Delay	Enter the maximum number of seconds to wait before next batch is sent to the destination.
Enabled	Enable this button to activate this Webhook.

Click the Save button at the bottom of the page. A slide-in banner on the top of the page will notify that the Webhook has been created and you will be redirected to the Webhook created page.
Copy the verification key and keep it safely. You will need this key to verify and decrypt the webhook payload.
Click Okay and you will be taken back to the Webhooks page.

How to Start Using the Webhook?

Step 1: Receive the payload

Payments Orchestrator will start sending Webhook payloads to the configured destination as soon as a Webhook is saved and enabled. The Webhook payload is sent in batches, where each batch contains an array of events.

Batches will be filled with events until either the maximum batch size is reached or the maximum batch time delay has passed, whichever comes first.

Batch time delay is measured from the moment the first message gets included in a batch.

Copy

Copied

{
    "batchId": "f76c3ef8-bfa0-461c-ac90-1e5f5af1cd59",
    "webhookId": "3845d770-f5a0-45b6-b146-0166fea4fcef",
    "timestamp": 1582631448782,
    "events":[
        {
            "eventType": "<event-type>",
            "messageId": "1d9f08d5-0954-865c-7168-7934d31c59d2",
            "timestamp": 1601462521732,
            ...
        },
        { ... },
        ...
    ]
}

Step 2: Verify the payload

The incoming Webhook batches include a digest header that can be used to prove the integrity of its contents. The example of the Request header is shown below.

Request Header SyntaxRequest Header ExamplePython Implementation

Copy

Copied

user-agent: Imburse
content-type: application/json;charset=utf-8
digest: sha-256=%ContentHash%

Copy

Copied

user-agent: Imburse
content-type: application/json;charset=utf-8
digest: sha-256=8fb733556d6f1feeb51d646bb9d627d5adbeccc9fa291413cedf37762389a0e4

Copy

Copied

import hashlib
import hmac
import base64

requestBody = bytes('{"batchId":"d1bb410d-5646-4928-922d-4a7e5424a606","webhookId":"b95398b7-7ba9-415c-993c-f0dbb3f4a012","timestamp":"1668467018334","events":[{"eventType":"CUSTOMER","customerRef":"David.Ferreira1668467005013","financialInstrumentIds":[],"metadata":{},"timestamp":1668467008243,"messageId":"e0d3e8d9-2e0c-8952-cff7-f36c8114a6c1"}]}', 'utf-8')
verificationKey = bytes('cnV/LPZCXYpaax9nLzYgMY5Rj+Vab9bzogfmBufSczA=', 'utf-8')
webhookDigest = '8fb733556d6f1feeb51d646bb9d627d5adbeccc9fa291413cedf37762389a0e4'
hash = hmac.new(verificationKey, requestBody, hashlib.sha256)
# to lowercase hexits
hash.hexdigest()

if(hash.hexdigest() == webhookDigest):
    print("They match")
    print(hash.hexdigest())
    print(webhookDigest)
else:
    print("They don't match")

To validate the integrity of the request:

Generate a HMAC SHA256 signature using the binary representation of the request body and the verification key you have for the Webhook subscription.
Compare the resulting HMAC digest against the digest from the request header. If they match, the request body has not been tampered with.

Step 3: Send Acknowledgement

After you have verified the payload integrity, you will have to send an acknowledgement back to the Payments Orchestrator application in the form of an HTTP status code. This code will be used to inform the application if the payload was received successfully.

Payments Orchestrator will consider any HTTP response code between 200 and 299 as a success. All other status codes will be considered a failed attempt.

In case of a failed attempt, Payments Orchestrator will retry sending the request three times on an escalating retry policy.

Troubleshooting

I want to deactivate a webhook.

To deactivate a webhook, click the Edit button next to the Webhook's name that you want to deactivate. On the Edit webhook page, disable the button next to Enabled label and click Save.

I want to see the batch messages sent through the webhook.

To view the batch messages, click the Message Batches button next to the Webhook's name. The Message Batches page appears with a list of all the Batches sent via the webhook.

I want to remove a webhook.

To remove a webhook, click the Delete button next to the Webhook's name that you want to delete. When prompted to continue, click Yes, delete.