What are webhooks?

There are two mechanisms for consuming updates from an API; polling and webhooks. Polling is a pull-based mechanism that requires the consumer (you) to make requests against the API to check for changes. Webhooks are a push-based mechanism, where the producer (Crezco) will send an event to an endpoint of your choosing to let you know something happened.

How do they work?

First, you register the endpoint you want to receive the events to via the Crezco Payables API. You can select which event types you want to receive events for.

We will then send webhook events as HTTP POST requests to any endpoints you have registered, whenever an event occurs. All your endpoint needs to do is return a 200 response code so we know you've received the message. If you don't return a 200 we will try again.

All of this is explained in more detail below.

Event Types

EventType	Description
PayRun	A status change has occurred to a Payrun
Payable	A status change has occurred to a Payable
Authorisation	A status change has occurred to a Payment Authorisation attempt
OrganisationOnboarding	A status change has occurred to an Organisation Onboarding attempt
BankAccount	A status change has occurred to a Bank Account
Feature	A change has occurred to the Organisation's supported features
Verification	A status change has occurred to an Organisation's KYC/KYB verification

See Statuses

More event types may be available in future updates to the API. These will be added in a backwards-compatible fashion.

Managing endpoints

Consumers are required to register their desired webhook endpoints via the API. This allows for programmatic registration and avoids the need to manage endpoints via dashboards or set them up in advance.

For applications that depend on webhooks for their operation we recommend checking that a webhook exists upon startup.

Requirements for registering an endpoint

An endpoint registration:

Must contain at least 1 EventType
Must be a unique by URL
Must be HTTPS with a minimum of TLS1.2
Must not contain query parameters

Registering an endpoint

In order to receive webhooks you must register at least one endpoint. This can be done by making a POST - Register webhook request with the endpoint and desired event type(s).

Example payload

{
  "eventType": "PayRun",
  "callback": "https://webhooks.example.org/crezco/payruns",
  "version": "2025-01-31"
}

Listing your endpoints

To get a list of all registered webhook endpoints you can make a GET - List existing webhooks for Partner request.

Example response

{
  "webHooks": [
    {
      "webHookId": "8cefae8a-ab99-4ce0-b364-1e4426c4dfda",
      "eventType": "PayRun",
      "callback": "https://webhooks.example.org/crezco/payruns",
      "version": "2025-01-31"
    }
  ]
}

Updating an endpoint

To update an existing endpoint registration you can make a PUT - Update webhook call with the updated information.

Deleting an endpoint

To delete an endpoint make a DELETE - Delete existing webhook call with the ID of the webhook you wish to delete.

Payloads

All payloads are sent as a JSON payload with a consistent format.

Fields

Field	Description
Events	An array of events. Will contain at least 1 event

Note that metadata fields to help with ingestion and observability may be added in future, in a backwards-compatible fashion.

Event Fields

Field	Description	Event Types
EventId	Unique numeric id to identify the event.	All
Type	The Event Type. For more details on event types see the definitions above.	All
Id	Id of the resource the event relates to. For example, if the Event Type is `PayRun` then this will be the PayRunId.	All
ParentType	Type of the resource's parent. Note: This is expected to be `PayRun` unless the Event Type is `Authorisation` in which case it will be `Batch`	`Payable`, `Authorisation`
ParentId	Id of the resource's parent. See ParentType for which type this relates to.	`Payable`, `Authorisation`
Status	The new status for the resource. For specific status values please see the Statuses page	All
Timestamp	The UTC timestamp that the status change was made.	All
OrganisationId	The Id of the Organisation that the resource belongs to.	All
PartnerClientId	The partner-provided Id that the resource belongs to.	All
PartnerEntityId	The partner-provided Id for the related resource, where applicable. For example, if the Event Type is `PayRun` then this will be the partner-supplied PayRunId.	`PayRun`, `Payable`
ParentPartnerEntityId	The partner-provided Id related to the resource's parent. To simplify processing this is only ever set to the partner entity ID for the owning PayRun.	`Payable`
Version	The API version that this webhook was raised from	All
Payload	JSON payload with additional event information	`OrganisationOnboarding`, `Payable`

ParentType and ParentId are only present on Payment events. A payment's parent may be either a payable or a group.

Headers

Header	Description
Crezco-Signature	The SHA256 signature for the payload. See the Signatures section below.
Date	The timestamp of when the request was made, for use in request verification.
Crezco-Public-Key-Id	The ID of the public key used for request verification. See the Signatures section below.

Example payload

{
  "events": [
    {
      "eventId": "762481ba-c31a-4a9c-a840-9edf58280a24",
      "type": "Authorisation",
      "id": "e92f011a-f879-4378-8d59-7a31f96febb6",
      "parentType": "Batch",
      "parentId": "d97161dc-c677-41c0-a220-d53738fc8d9d",
      "status": "UserAuthorising",
      "timestamp": "2024-06-28T20:16:07.0278612Z",
      "organisationId": "4803feaa-7d7b-4c72-bc9e-5ee69f0dd4c7",
      "partnerClientId": "crezdemo_1719605590",
      "partnerEntityId": null,
      "parentPartnerEntityId": null,
      "payload": null,
      "version": "2024-06-30"
    },
    {
      "eventId": "0cfa7be8-aff1-4e42-a907-9b1395de6df4",
      "type": "Payable",
      "id": "d66e61b1-b074-4dbe-9b4e-60d14fe0cbc1",
      "parentType": "PayRun",
      "parentId": "d43b5a74-2269-468e-b9b3-0fcc7561ed5d",
      "status": "UserInitiationInProgress",
      "timestamp": "2024-06-28T20:16:07.1642286",
      "organisationId": "4803feaa-7d7b-4c72-bc9e-5ee69f0dd4c7",
      "partnerClientId": "crezdemo_1719605590",
      "partnerEntityId": "9f423605-319b-49fc-8438-b4fc3c6e359c",
      "parentPartnerEntityId": "25fe981c-e295-4f98-9721-9a5289098407",
      "payload": {
        "amount": {
          "currencyCode": "EUR",
          "amountInMinorUnits": 6006,
          "currencyConversion": {
            "isEstimated": false,
            "rate": 1.23903643,
            "fees": {
              "transferFee": {
                "amountInMinorUnits": 50,
                "currencyCode": "GBP"
              },
              "exchangeFee": {
                "amountInMinorUnits": 25,
                "currencyCode": "GBP"
              }
            },
            "fundingAmount": {
              "amountInMinorUnits": 4923,
              "currencyCode": "GBP"
            }
          },
          "amountReturned": null
        }
      },
      "version": "2024-06-30"
    }
  ]
}

Delivery

Requirements for receiving payloads

For payload delivery the following apply:

Endpoint must respond with 200 (OK) to confirm acceptance.
- Any other response will be treated as a failure.
Endpoint must respond within 5 seconds.
- After this time any response will be treated as a failure due to timeout.
Payloads shall be delivered at least once.
- Consumers must be prepared to receive duplicate payloads due to timeout and retry policies.
Payloads may arrive out-of-order.
- Consumers must be prepared to receive out-of-order payloads due to timeout and retry policies.
Payloads may contain events for multiple unrelated pay-runs.
- We try to batch events to minimise traffic where possible. The ability to do this is based on downstream banking dependencies and may vary, and is therefore done on a best-efforts basis.

Retries

If a payload cannot be delivered then Crezco will retry using an exponential backoff policy. If the webhook cannot be delivered successfully within 48 hours we will mark your endpoint as inactive and notify you.

All undelivered payloads will be stored for 30 days and replayed to endpoints when they are marked as active again.

Signatures

A signature should be used to verify the webhook payload has been sent from Crezco. The process of computing a signature is:

Get the raw UTF8 bytes of the body of the webhook message
Get the public key ID from the Crezco-Public-Key-Id header of the request
Fetch the full public key from the GET Webhook Key endpoint, passing in the public key ID
- You can and should cache the full public key, as it will never change for a given public key ID
Decode the public key from Base64 encoding into public key bytes
Instantiate a ECDSA implementation and import the public key bytes as subject public key info
Get the timestamp from the Date header of the request
Decode the date from Base64 encoding into date bytes
Concatenate the date bytes followed by the body bytes, into what we will call data bytes
Get the signature from the Crezco-Signature header of the request
Decode the signature from Base64 encoding into signature bytes
Verify the ECDSA signature using the data bytes and the signature bytes, using SHA256 hash algorithm

A sample pseudo-implementation in C# may be:

byte[] bodyBytes = Encoding.UTF8.GetBytes(webhookBody);

var publicKeyId = headers["Crezco-Public-Key-Id"];
var publicKeyDto =
  await crezcoHttpClient.GetFromJsonAsync<PublicKeyDto>(
  	$"https://api.partners.crezco.com/webhooks/keys/{publicKeyId}");
byte[] publicKeyBytes = Convert.FromBase64String(publicKeyDto.PublicKey);

using var ecdsa = ECDsa.Create();
ecdsa.ImportSubjectPublicKeyInfo(publicKeyBytes, out _);

var date = headers["Date"];
byte[] dateBytes = Encoding.UTF8.GetBytes(date.ToString());

byte[] dataBytes = [..dateBytes,..bodyBytes];

var signature = headers["Crezco-Signature"];
byte[] signatureBytes = Convert.FromBase64String(signature.ToString());

bool verified = ecdsa.VerifyData(dataBytes, signatureBytes, HashAlgorithmName.SHA256);

You should verify all incoming webhooks using this method. If the signature does not match you should reply with a 401 (Unauthorized) status code.

Testing and Troubleshooting

We recommend the use of a tool such as webhook.site to aid with testing payload receipt from our testing environment. You should be able to capture payloads and replay them to yourself, or craft your own test payloads and signatures.

Please make sure your endpoint is able to accept inbound internet traffic and is not blocked by any firewall or routing rules. If you have any difficulty please reach out to our technical team.

Webhooks and API Versions

Webhooks are created in the context of an API Version. When you call the Register webhook endpoint you will create a webhook for the version of the API that you are currently using (see Versioning for more details on API Versions).

All webhook registrations will be triggered when an object state changes that is relevant to that API version. For example if you register a webhook against version 2023-07-17 of the API and another webhook against version 2024-07-01 of the API, they will both receive a request when a Pay Run status changes, but only the latter webhook will receive a request when a Verification status changes.

Webhook registrations will each receive updates describing the statuses that are valid for their respective versions, and if an object moves into a status that is not relevant to an older version, that webhook registration will not receive the particular event request describing that status.

Webhook Migration for API Version Changes

When you migrate to a new version of the API you should perform the following steps to migrate your webhooks:

Prepare your new webhook endpoints to receive the new version of webhook events
Call Register webhook for each of the webhook events that you wish to subscribe to in the new version of the API
Call Delete existing webhookfor each webhook for the old version to which you are still subscribed

You may have webhooks registered for multiple versions of the API at any time.