Skip to content

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#

  1. Open the dashboard and go to API keys. Copy the Webhook signing key shown under Webhook verification.
  2. 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.

  1. Read the raw body before parsing it.
  2. Compute HMAC-SHA512 of the raw body with your signing key and hex-encode it.
  3. Compare it with X-Webhook-Signature-512 in constant time.
  4. Reject the request with 401 if 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);

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#

json
{
  "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_id before you act on it and acknowledge duplicates without processing them again.
  • Ordering: deliveries may arrive out of order. For payments, compare content.object.updated with what you stored and apply only newer states.
  • Source of truth: when in doubt, retrieve the object with GET /payments/{payment_id} or GET /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.