Guides
Webhooks
Receive signed HTTPS notifications in your own systems when a payment's status changes.
On this page
- Overview
- Setting up an endpoint
- Endpoint requirements
- Events
- Payload
- Subscription events
- Customer subscription events
- Finance events
- Saved card and account standing events
- Request headers
- Verifying signatures
- Verification code
- Responding and retries
- Duplicates and ordering
- Rotating the signing secret
- Testing
- Receiver checklist
Overview#
Webhooks let CentraPoint push payment updates to your systems: when a payment completes, fails, is cancelled or is refunded, CentraPoint sends a signed JSON POST to the HTTPS endpoints you configure. This is the recommended way to learn about payment outcomes. Keep the Transactions API as a fallback for reconciliation and for payments you have not heard about.
Setting up an endpoint#
- In the dashboard, go to Settings → Webhooks (administrators only; requires a plan that includes the REST API).
- Under Add endpoint, enter your HTTPS URL, an optional description, and the events to receive. Selecting no events subscribes to all of them.
- Copy the signing secret (
whsec_…). It is shown only once; store it like a password. - Click Send test event to check your receiver.
You can have up to 5 endpoints per organisation. Each can be disabled, deleted, or have its secret rotated, and you can change which events it receives at any time without re-creating it, so its URL and signing secret stay the same. Selecting no events, or all of them, subscribes the endpoint to every event, including ones added in future. The page also shows a delivery log with each attempt's status and a Resend button.
Endpoint requirements#
- HTTPS only, on port 443 or 8443.
- No credentials in the URL (
https://user:pass@…is rejected). - The host must resolve to a public internet address. Private, loopback, link-local, carrier-grade NAT and similar ranges are rejected. The check runs when you save the endpoint and again before every delivery.
- Redirects are not followed. A
3xxresponse counts as a failed delivery, so configure the final URL.
Events#
| Event | Sent when |
|---|---|
payment.complete | complete: money received and verified. Fulfil the order. |
payment.failed | failed: declined, rejected, or a debit order returned unpaid. |
payment.cancelled | cancelled: the payer cancelled or abandoned checkout. |
payment.refunded | refunded: fully refunded. |
payment.partially_refunded | partially_refunded: part of the amount refunded. |
invoice.paid | An invoice is fully paid (through a gateway, an allocated payment or a recorded offline payment). data is the invoice object, including its payments. |
invoice.partially_paid | An invoice received a payment but still has a balance. data is the invoice. |
invoice.cancelled | An invoice was cancelled. data is the invoice. |
invoice.created | An invoice was created (API, dashboard, quote conversion or subscription billing). data is the invoice. See Finance events. |
invoice.sent | An invoice was created as sent (emailed or not), or a draft was sent or issued without email. data is the invoice. |
quote.created | A quote was created. data is the quote object. |
quote.updated | A quote's lines or details were edited, or it was moved back to draft. |
quote.sent | A quote was marked sent. |
quote.accepted | A quote was marked accepted. |
quote.declined | A quote was marked declined. |
quote.expired | A sent quote passed its expiry date. |
quote.invoiced | A quote was converted into an invoice (data.invoice is set; invoice.created is sent too). |
credit_note.created | A credit note was created. data is the credit note object. |
credit_note.issued | A credit note was issued (sent right after credit_note.created when it is created as issued). |
credit_note.applied | Credit was applied to an invoice. |
credit_note.refunded | Credit was paid back: against a payment, by scheduled payout, or recorded manually. |
credit_note.voided | A credit note was voided. |
payout.scheduled | A payout was scheduled. data is the payout object (no bank details). |
payout.submitted | The payout was sent to Netcash in a batch. |
payout.paid | The batch was loaded and the action date reached. |
payout.failed | Netcash rejected the payout or the upload failed (data.failureReason). |
payout.cancelled | A scheduled payout was cancelled. |
customer.payment_method.added | A customer saved a card. data is the card. See Saved card and account standing events. |
customer.payment_method.removed | A saved card was removed. |
customer.payment_method.expiring | A saved card expires within 30 days (once per card). |
customer.standing.changed | A customer's account standing changed (grace started, locked, unlocked, resolved). |
subscription.activated | The first payment of a subscription completed. See Subscription events. |
subscription.charged | A renewal collection completed. |
subscription.payment_failed | A renewal collection failed. |
subscription.cancelled | The subscription was cancelled (API, dashboard or gateway). |
subscription.paused | The subscription was paused (API or dashboard). |
subscription.resumed | A paused subscription was resumed (API or dashboard). |
subscription.created | A customer subscription was created (dashboard, API, checkout or portal). See Customer subscription events. |
subscription.renewed | A customer subscription's renewal was paid, or an overdue payment was recovered (recovered: true). |
subscription.trial_ended | A customer subscription's trial ended; the first charge is issued. |
subscription.past_due | A customer subscription payment failed and dunning started. |
subscription.plan_changed | A customer subscription moved to another plan or quantity. |
subscription.updated | Metadata, externalReference or the billing date changed, or a cancellation at period end was scheduled or withdrawn. |
subscription.expired | A customer subscription ended on its own: fixed term completed, first payment never arrived, or dunning set to expire. |
checkout.completed | A checkout session completed: paid, or started a trial or free plan. data is the checkout session (object: "checkout_session"). |
checkout.failed | A checkout session's payment failed or was cancelled. data is the checkout session. Nothing is sent when a session expires. |
eft.proof_received | Proof of payment was uploaded for an EFT order. data is the EFT order. |
eft.rejected | Staff rejected the proof. data is the EFT order (with rejectionReason). |
eft.expired | An EFT order expired unpaid. data is the EFT order. |
eft.cancelled | An EFT order was cancelled through the API or the dashboard. data is the EFT order. |
reconciliation.completed | A reconciliation run finished. data: runId, status, exceptions, lineCount, statementDate, totals, account (Netcash account and its gateways) and summary (matched, unmatched, notReceived, balance view). |
webhook.test | Not a payment event. Sent only by Send test event; its data is { "message": "CentraPoint webhook test" }. |
Events are emitted from every path that changes a status: gateway notifications, on-demand verification, debit order settlement and unpaids, reconciliation, refunds, and the payer cancelling. pending produces no event. Remember that a later event can supersede an earlier one; for example payment.cancelled followed by payment.complete when a gateway confirms late (see the status lifecycle).
Payload#
{
"id": "evt_3f9a1c7b2e4d6f8091a2b3c4",
"type": "payment.complete",
"created": "2026-09-25T08:14:04.201Z",
"data": {
"reference": "CP-20260925-9F3A1C7B",
"status": "complete",
"amount": 499,
"currency": "ZAR",
"type": "once",
"gateway": "payfast",
"sandbox": false,
"providerRef": "2458761",
"paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
"externalReference": "ORDER-1001",
"eftOrderId": null,
"invoice": {
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"status": "paid",
"externalReference": "ORDER-1001"
},
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001"
},
"metadata": {
"cartId": "c_8841"
},
"renewal": false,
"parentReference": null,
"subscriptionId": null,
"refundedAmount": 0,
"paidAt": "2026-09-25T08:14:03.512Z"
}
}| Field | Type | Description |
|---|---|---|
idrequired | string | Unique event ID (evt_…). The same event sent to several endpoints, retried or resent keeps the same ID. Use it to de-duplicate. |
typerequired | string | Event type, see Events. |
createdrequired | string (date-time) | ISO 8601 UTC time the event was created. |
data.referencerequired | string | Payment reference. Look it up with GET /api/v1/transactions/{reference}. |
data.statusrequired | string | Transaction status when the event was created. |
data.amountrequired | number | Gross amount in major units. |
data.currencyrequired | string | ISO 4217 code. |
data.typerequired | string | once, recurring, invoice, debit_order or eft. |
data.gatewayrequired | string | Gateway type, e.g. payfast. |
data.sandboxrequired | boolean | true when a gateway set to sandbox (test) mode in CentraPoint processed the payment. For gateways whose test mode CentraPoint selects no real money moved: do not settle real invoices or orders with it. Netcash, DPO and PayGate with your own credentials only repeat the CentraPoint setting; Manual EFT is always false (details). |
data.providerRefrequired | string | null | The gateway's own payment ID. |
data.paymentLinkIdrequired | string | null | Payment link the payment was made through. |
data.externalReferencerequired | string | null | The payment link's (or EFT order's) externalReference, i.e. your order ID. |
data.eftOrderIdrequired | string | null | EFT order the payment belongs to (Manual EFT). |
data.invoicerequired | object | null | { id, number, status, externalReference } when the payment is for an invoice. |
data.customerrequired | object | null | { id, externalReference } of the paying customer. |
data.metadatarequired | object | The payment link's (or EFT order's) metadata; {} when none. |
data.renewalrequired | boolean | True for later collections of a subscription. |
data.parentReferencerequired | string | null | For renewals: reference of the first payment. |
data.subscriptionIdrequired | string | null | Subscription started by the payment link, if any. |
data.refundedAmountrequired | number | Total refunded so far (excluding failed refunds); 0 if none. |
data.paidAtrequired | string | null | When the payment completed. |
The table above describes payment.* events. Unlike the Transactions API, their payload does not include fee, net, payer email or refund detail; call the Transactions API if you need those. invoice.* events carry the full invoice object as data, and eft.* events the EFT order object.
Subscription events#
subscription.* events carry the subscription object plus subscriptionId (same as id). activated, charged and payment_failed also carry the payment that triggered them and the period it pays for:
{
"id": "evt_2a4c6e8f0b1d3f5a7c9e1b3d",
"type": "subscription.charged",
"created": "2026-10-25T08:14:05.000Z",
"data": {
"id": "cmg2s5b8k0007sub0001abcd",
"status": "active",
"frequency": "monthly",
"amount": 499,
"currency": "ZAR",
"gateway": "payfast",
"paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
"externalReference": "SUB-ACME-PRO",
"metadata": {
"plan": "pro"
},
"createdAt": "2026-09-25T08:14:04.000Z",
"updatedAt": "2026-09-25T08:14:04.000Z",
"subscriptionId": "cmg2s5b8k0007sub0001abcd",
"payment": {
"reference": "CP-20260925-9F3A1C7B-2458799",
"amount": 499,
"currency": "ZAR",
"status": "complete",
"paidAt": "2026-10-25T08:14:03.000Z"
},
"periodStart": "2026-10-25T08:14:03.000Z",
"periodEnd": "2026-11-25T08:14:03.000Z"
}
}periodStartis when the payment was made;periodEndadds one billing interval. Forpayment_failedboth arenull, because no period was paid.subscription.cancelled,subscription.pausedandsubscription.resumedcarry the subscription only, with nopaymentor period fields.- You also receive the matching
payment.*event for each collection; handle whichever suits your integration, and de-duplicate on the subscription and payment reference rather than assuming both arrive in order.
Customer subscription events#
Customer subscriptions (packages & plans) send subscription.created, .activated, .renewed, .trial_ended, .payment_failed, .past_due, .paused, .resumed, .plan_changed, .updated, .cancelled and .expired. Their data is the customer subscription object with object: "customer_subscription" and subscriptionId, plus event-specific fields. Subscriptions your platform bills itself (collectionMethod: external, mirror mode) send no events.
| Event | Extra fields in data |
|---|---|
activated, renewed | transactionId, invoiceId of the payment; renewed adds recovered: true when an overdue payment was recovered. |
payment_failed | transactionId, invoiceId, reason |
past_due | reason, attempt |
plan_changed | previousPlan: { id, name }, previousAmount |
updated | cancelAtPeriodEnd (and endsAt) when a cancellation at period end was scheduled or withdrawn |
cancelled, expired | reason |
Finance events#
Invoice, quote, credit note and payout events let your own systems (for example an ERP or billing platform) mirror every record, whichever path (API, dashboard, scheduled jobs) made the change. Their data is exactly the object the matching GET endpoint returns, so one parser handles both:
| Events | data | Same as |
|---|---|---|
invoice.created, .sent, .paid, .partially_paid, .cancelled | Invoice object | GET /api/v1/invoices/{id} |
quote.* | Quote object (object: "quote") | GET /api/v1/quotes/{id} |
credit_note.* | Credit note object (object: "credit_note") | GET /api/v1/credit-notes/{id} |
payout.* | Payout object (object: "payout"), never with bank details | GET /api/v1/payouts/{id} |
{
"id": "evt_5c7e9a1b3d5f7a9c1e3b5d7f",
"type": "quote.accepted",
"created": "2026-09-29T11:02:10.000Z",
"data": {
"object": "quote",
"id": "cmg3q1a2b0001quo0001abcd",
"number": "QUO-000017",
"status": "accepted",
"currency": "ZAR",
"total": 5750,
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": null,
"acceptedAt": "2026-09-29T11:02:09.000Z"
}
}datais built when the event is created, so it reflects the record at that moment. One action can send several events (e.g.quote.invoicedandinvoice.created, orcredit_note.appliedandinvoice.paid); de-duplicate on the eventidand usedata.updatedAtto ignore stale ones.- Deleting a draft quote sends no event. When a credit note's payout is cancelled or fails, its reserved amount is released and you receive
payout.cancelled/payout.failed(the payout'screditNotetells you which credit note to re-fetch).
Saved card and account standing events#
customer.payment_method.added, .removed and .expiring carry the card object (brand, last four digits, expiry; never the card number) plus customer: { id, externalReference }. customer.standing.changed carries the standing object with change (grace_started, locked, unlocked, resolved, reason_changed), previous (status and reason before) and customer. Each change is sent once; use the standing endpoint for the current state.
Request headers#
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | CentraPoint-Webhooks/1.0 |
CentraPoint-Event | The event type, e.g. payment.complete. |
CentraPoint-Delivery | ID of this delivery (constant across its retries; a manual resend gets a new delivery ID but the same event id). |
CentraPoint-Signature | t=<unix seconds>,v1=<hex signature> |
Verifying signatures#
Always verify the signature before trusting a webhook: anyone can send a request to your URL. The signature is:
v1 = hex( HMAC-SHA256( key = signing secret, message = "<t>." + <raw request body> ) )- Read the raw request body exactly as received. Do not parse and re-serialise the JSON first.
- Split
CentraPoint-Signatureon,and readtandv1. - Reject the request if
tis more than 5 minutes away from your current time (protects against replay). Keep your server clock in sync. - Compute the HMAC with your signing secret, used as-is including the
whsec_prefix (it is not base64-decoded), overt, a dot, and the raw body. - Compare with
v1using a constant-time comparison. Reject on mismatch.
Verification code#
# Send a correctly signed test event to your own receiver (bash + openssl).
SECRET="whsec_your_signing_secret"
BODY='{"id":"evt_local_test","type":"webhook.test","created":"2026-09-25T08:00:00.000Z","data":{"message":"CentraPoint webhook test"}}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -X POST "https://example.com/webhooks/centrapoint" \
-H "Content-Type: application/json" \
-H "CentraPoint-Event: webhook.test" \
-H "CentraPoint-Delivery: local-test" \
-H "CentraPoint-Signature: t=$T,v1=$SIG" \
--data-raw "$BODY"Responding and retries#
- Respond with any 2xx status within 10 seconds. Do slow work (emails, fulfilment) after responding, for example via a queue.
- Anything else (non-2xx, redirect, timeout, connection or TLS error) is a failed attempt.
- Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours: 8 attempts in total over about 2 days. After the last attempt the delivery is marked failed and your team gets an in-app notification (at most one per endpoint per day).
- Failed deliveries can be resent from the delivery log in Settings → Webhooks. Disabled endpoints receive nothing.
Duplicates and ordering#
- Deliveries can repeat (retries after a timeout, manual resends). Store processed event
ids and ignore ones you have seen, and make fulfilment idempotent perdata.reference. - Ordering is not guaranteed. A retried older event can arrive after a newer one. Use the event as a trigger: when in doubt, fetch the current state with GET /api/v1/transactions/{reference} and act on that.
- Check
data.externalReference,data.amountanddata.currencyagainst your order before fulfilling.
Rotating the signing secret#
Click Rotate secret on the endpoint to generate a new secret (shown once). The old secret stops being used immediately, so update your receiver straight away. Deliveries that fail during the switch are retried and will then be signed with the new secret.
Testing#
- Send test event in the dashboard sends a signed
webhook.testevent and shows the result immediately. - Make a sandbox payment through a payment link to receive real
payment.*events. - Use the cURL tab above to exercise your receiver locally with a correctly signed request.
Receiver checklist#
- HTTPS endpoint on port 443 or 8443 with a public address, no redirects.
- Verifies the signature over the raw body, with a timing-safe compare and a 5-minute timestamp tolerance.
- Responds 2xx within 10 seconds and processes asynchronously.
- De-duplicates on event
idand tolerates out-of-order events. - Handles unknown event types gracefully (new ones may be added): respond 2xx and ignore.
- Keeps a polling fallback with the Transactions API for payments it has not heard about.