Set up and Use a Webhook

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 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 Duck Creek Payments.

Before you Start

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

How it works?

  1. When you set up and configure a Webhook, you will receive a verification key.

  2. Whenever an event is processed within the Payments application, it will send event-related webhook payloads to the HTTPS destination that you specified in the setup.

  3. You can then consume the payload directly or verify the payload before consuming it.

  4. Finally, you will send an acknowledgement message back to the Payments application in the form of an HTTP status code.

How to Set Up Webhooks?

  1. Login to the Tenant Portal.

  2. Select Webhooks under Developers menu from the left sidebar. The Webhooks page appears with a list of all the created Theme templates (if any).

  3. Click the button on the top-right corner of the page. The Add webhook page appears.

  4. Fill the available fields with relevant information. Refer to the table below for more information on each fields.
DestinationEnter the full URL to an endpoint that Payments should post notifications to.

EventsSelect one or more events whose payloads you should receive through this Webhook. Payments 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 SizeEnter the maximum number of events that should be rolled up into a batch before the payload is dispatched to the destination.
Maximum Batch Time DelayEnter the maximum number of seconds to wait before next batch is sent to the destination.
EnabledEnable this button to activate this Webhook.
  1. 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.

  2. Copy the verification key and keep it safely. You will need this key to verify and decrypt the webhook payload.

  3. Click Okay and you will be taken back to the Webhooks page.

How to Start Using the Webhook?

Step 1: Receive the payload

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

    "batchId": "f76c3ef8-bfa0-461c-ac90-1e5f5af1cd59",
    "webhookId": "3845d770-f5a0-45b6-b146-0166fea4fcef",
    "timestamp": 1582631448782,
            "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
user-agent: Imburse
content-type: application/json;charset=utf-8
digest: sha-256=%ContentHash%
user-agent: Imburse
content-type: application/json;charset=utf-8
digest: sha-256=8fb733556d6f1feeb51d646bb9d627d5adbeccc9fa291413cedf37762389a0e4
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 =, requestBody, hashlib.sha256)
# to lowercase hexits

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

To validate the integrity of the request:

  1. Generate a HMAC SHA256 signature using the binary representation of the request body and the verification key you have for the Webhook subscription.

  2. 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 application in the form of an HTTP status code. This code will be used to inform the application if the payload was received successfully.

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


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.

Copyright 2024 Duck Creek Technologies. All Rights Reserved.