Webhooks

Configure your webhook alerting rules

In order to maintain a performant and event based system, you should subscribe to webhook events, these will tell you when an organisation has made or failed to make a payment.

Currently all webhooks are composed of:

  • A Type – Payment is the only type supported as of today
  • An EventType
    • PaymentAll – Triggered for any (of the following) Payment related events
    • PaymentPending – Triggered when a Payment has been created
    • PaymentFailed – Triggered when a Payment has failed
    • PaymentCompleted – Triggered when a Payment has been completed
  • A Callback – where the payload will be sent to notify of the event

A Webhook is unique according to those 3 properties. It is possible to subscribe to the same Type + Event Type for different Callbacks.

Webhook structure

All webhooks are executed using a POST method to the defined callback uri.

Sample Webhook

{
    "type": "Payment",
    "eventType": "PaymentCompleted",
    "id": "02ea8cc2-a831-4e3a-87e6-2c25c7bf42dc",
    "metadata": {
      "payDemandId": "a1b4591e-4d93-4978-bea1-f9611d8712cd"
    },
    "partnerMetadata": {},
    "timestamp": "2023-09-18T11:25:56.0702497Z"
}

Payload structure

FieldDescriptionType
TypeWebhook typeWebHookType
EventTypeType of eventWebHookEventType
IdUUID of the pay demandUUID
MetadataAdditional informationDictionary
TimestampUTC timestamp of the eventdatetime

🚧

Response status

The webhook request is expected to return a code in 2xx range. Any other code returned may result in webhook being deactivated.

Add a WebHook

To add a WebHook subscription, POST a configuration payload to the /v1/webhooks endpoint.

curl -X POST "https://api.sandbox.crezco.com/v1/webhooks" -H "accept: text/plain" -H "X-Crezco-Key: {API-KEY-VALUE}" -H "Content-Type: application/json" -d "{\"type\":\"Payment\",\"eventType\":\"PaymentAll\",\"callback\":\"https://webhook.site/b83e2720-f733-4fd7-824f-824fc85c2161\"}"

This will return the newly create WebHook identifier.

List the WebHooks

To list the currently configured WebHooks, send an HTTP GET request to the /v1/webhooks endpoint.

curl -X GET "https://api.sandbox.crezco.com/v1/webhooks" -H "accept: text/plain" -H "X-Crezco-Key: {API-KEY-VALUE}"

The response will contain an array of WebHooks subscription.

Remove a WebHook

To remove a currently configured WebHook, send an HTTP DELETE request to the /v1/webhooks/{webhookId} endpoint.

curl -X DELETE "https://api.sandbox.crezco.com/v1/webhooks/02c8d4b0-affb-4413-94cc-d48cafce407c" -H "accept: */*" -H "X-Crezco-Key: {API-KEY-VALUE}"

If the WebHook was deleted, the endpoint will return an HTTP 200 response with no content.

Test a WebHook

Making use of the https://webhook.site online tool makes it easy to test a WebHook configuration, without having a running and hosted environment: