Webhooks
Receive signed Cardencer events for payments, refunds and disputes, verify the HMAC-SHA512 signature and process them idempotently.
Webhooks tell your server when something happens to a payment, refund or dispute, so you do not have to poll. Each delivery is an HTTPS POST with a JSON body, signed with your webhook signing key.
1. Create an endpoint#
Expose a public HTTPS endpoint that accepts POST requests. Return a 2xx status once you have stored the event; do slow work (emails, ERP sync) afterwards.
2. Register the endpoint#
- Open the dashboard and go to API keys. Copy the Webhook signing key shown under Webhook verification.
- Send your endpoint URL to Cardencer support, saying whether it is for sandbox or live. Cardencer registers it on your business profile and confirms when deliveries start.
If you use a plugin, the plugin displays its own webhook URL: register that one.
3. Verify the signature#
Cardencer computes an HMAC-SHA512 of the exact raw request body with your webhook signing key, and sends the lowercase hex digest in the X-Webhook-Signature-512 header.
- Read the raw body before parsing it.
- Compute HMAC-SHA512 of the raw body with your signing key and hex-encode it.
- Compare it with
X-Webhook-Signature-512in constant time. - Reject the request with
401if they differ or the header is missing.
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/webhooks/cardencer", express.raw({ type: "application/json" }), (req, res) => {
const received = req.get("X-Webhook-Signature-512") ?? "";
const expected = crypto.createHmac("sha512", process.env.CARDENCER_WEBHOOK_KEY).update(req.body).digest("hex");
const valid = received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
if (!valid) return res.sendStatus(401);
const event = JSON.parse(req.body.toString("utf8"));
handleEvent(event); // store event.event_id first, see "Duplicates" below
res.sendStatus(200);
});
app.listen(3000);import hashlib, hmac, json, os
from flask import Flask, request, abort
app = Flask(__name__)
@app.post("/webhooks/cardencer")
def cardencer_webhook():
raw = request.get_data()
expected = hmac.new(os.environ["CARDENCER_WEBHOOK_KEY"].encode(), raw, hashlib.sha512).hexdigest()
received = request.headers.get("X-Webhook-Signature-512", "")
if not hmac.compare_digest(expected, received):
abort(401)
event = json.loads(raw)
handle_event(event) # store event["event_id"] first
return "", 200<?php
$raw = file_get_contents('php://input');
$expected = hash_hmac('sha512', $raw, getenv('CARDENCER_WEBHOOK_KEY'));
$received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE_512'] ?? '';
if (!hash_equals($expected, $received)) {
http_response_code(401);
exit;
}
$event = json_decode($raw, true);
handle_event($event);
http_response_code(200);Troubleshooting:
- Signature does not match: you are hashing parsed and re-serialised JSON. Hash the raw bytes.
- Header missing: check the header name (
X-Webhook-Signature-512) and that your proxy forwards it. - Wrong key: sandbox and live have different signing keys.
Event payload#
{
"merchant_id": "merchant_1700000000",
"event_id": "evt_018c4f3f6a1d7b2e9c",
"event_type": "payment_succeeded",
"timestamp": "2026-11-20T10:15:03.000Z",
"content": {
"type": "payment_details",
"object": {
"payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
"status": "succeeded",
"amount": 4900,
"amount_received": 4900,
"currency": "EUR",
"customer_id": "cus_58211",
"payment_method_id": "pm_lmTnIO5EdCiiOrRqT2RF",
"updated": "2026-11-20T10:15:02.000Z"
}
}
}content.type is payment_details, refund_details or dispute_details; content.object is the full payment, refund or dispute, as returned by the API.
Event types#
| Event | When |
|---|---|
payment_succeeded |
The payment is captured. Fulfil the order. |
payment_failed |
The payment was declined or failed. |
payment_processing |
The acquirer is still processing. |
payment_authorized |
Authorized and waiting for capture. |
payment_captured |
A manual capture completed. |
payment_cancelled |
The payment was cancelled before capture. |
action_required |
The customer must complete an action such as 3D Secure. |
refund_succeeded |
A refund went through. |
refund_failed |
A refund failed. |
dispute_opened, dispute_challenged, dispute_won, dispute_lost, dispute_accepted, dispute_expired, dispute_cancelled |
Dispute lifecycle. |
Retries#
A delivery succeeds when your endpoint returns 2xx. Otherwise Cardencer retries 16 times over about 24 hours:
| Retry | Delay |
|---|---|
| 1st | 1 minute after the first attempt |
| 2nd and 3rd | 5 minutes |
| 4th to 8th | 10 minutes |
| 9th to 13th | 1 hour |
| 14th to 16th | 6 hours |
Duplicates and ordering#
- Duplicates: retries can deliver the same event twice. Store each
event_idbefore you act on it and acknowledge duplicates without processing them again. - Ordering: deliveries may arrive out of order. For payments, compare
content.object.updatedwith what you stored and apply only newer states. - Source of truth: when in doubt, retrieve the object with
GET /payments/{payment_id}orGET /refunds/{refund_id}.
Test webhooks#
In the sandbox, register a tunnel URL (for example from ngrok http 3000) and run the quickstart payment: you receive payment_succeeded within seconds.