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
Field | Description | Type |
---|---|---|
Type | Webhook type | WebHookType |
EventType | Type of event | WebHookEventType |
Id | UUID of the pay demand | UUID |
Metadata | Additional information | Dictionary |
Timestamp | UTC timestamp of the event | datetime |
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:
- Open Swagger
- Configure the API Key
- Add a WebHook using a Callback like https://webhook.site/b83e2720-f733-4fd7-824f-824fc85c2161
- Create a new User
- Create a PayDemand
- Get the PayDemand payment url
- Open https://webhook.site/#!/b83e2720-f733-4fd7-824f-824fc85c2161 in first tab
- Open https://app.sandbox.crezco.com/payment/{encodedPayDemandId} in a second tab
- Complete successfully a payment, in the second tab
- Check the payloads received, in the first tab https://webhook.site/#!/b83e2720-f733-4fd7-824f-824fc85c2161