Webhooks are callbacks that notify events in your account. A webhook will make an HTTP request to your application (usually by the POST method), whose body will contain an object describing the associated event.For example: when a capture of an authorization is generated, a webhook allows you to receive a notification so that you can take an action, such as sending a thank-you email to the customer.Webhooks are helpful in two situations:When a generated event is not a direct result of a call to the API — for example, a chargeback.
When services or features need the response to a call, but they do not perform it directly — for example, an accounting service that needs to update records when a transaction is generated.
Updating a customer's membership in your database when payment is successful.
Recording an accounting entry after a transaction is made.
Card Present webhooks can only be set up through the Console. Webhooks through the API are not supported.
Consume a Webhook#
Create an endpoint to receive webhooks — simply add a new path with the desired URL to your application. Webhook data is sent as JSON in the body of the POST call.
Security#
Encryption#
You may use HTTP or HTTPS URLs for webhooks. HTTPS is recommended when handling sensitive data or to protect against replay attacks.Authentication#
To verify that webhook notifications originate from Kushki, check the following headers on every incoming request:| Header | Description |
|---|
X-Kushki-Key | Your merchant ID. |
X-Kushki-Signature | HMAC SHA256 signature of the request body + timestamp, using your webhook signature ID. |
X-Kushki-SimpleSignature | HMAC SHA256 signature of the X-Kushki-Id value, using your webhook signature ID. |
X-Kushki-Id | Request timestamp in Unix format. |
Kushki static IPs for webhook delivery:Production: 34.230.185.20
How to get the Webhook Signature#
Go to Desarrolladores > Webhooks in the Kushki Console. Your webhook signature is displayed at the top of the page.
Signature verification examples#
X-Kushki-Signature#
X-Kushki-SimpleSignature#
Webhook event types#
Depending on the operations you have integrated, webhook bodies will follow one of these structures:Card Payments — charge, preAuth, capture, reversal, void, balance inquiry
Got a suggestion on this documentation? Contact us.
