CentraPoint

Guides

Webhooks

Receive signed HTTPS notifications in your own systems when a payment's status changes.

On this page

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#

  1. In the dashboard, go to Settings → Webhooks (administrators only; requires a plan that includes the REST API).
  2. Under Add endpoint, enter your HTTPS URL, an optional description, and the events to receive. Selecting no events subscribes to all of them.
  3. Copy the signing secret (whsec_…). It is shown only once; store it like a password.
  4. 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 3xx response counts as a failed delivery, so configure the final URL.

Events#

Webhook events
EventSent when
payment.completecomplete: money received and verified. Fulfil the order.
payment.failedfailed: declined, rejected, or a debit order returned unpaid.
payment.cancelledcancelled: the payer cancelled or abandoned checkout.
payment.refundedrefunded: fully refunded.
payment.partially_refundedpartially_refunded: part of the amount refunded.
invoice.paidAn 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_paidAn invoice received a payment but still has a balance. data is the invoice.
invoice.cancelledAn invoice was cancelled. data is the invoice.
invoice.createdAn invoice was created (API, dashboard, quote conversion or subscription billing). data is the invoice. See Finance events.
invoice.sentAn invoice was created as sent (emailed or not), or a draft was sent or issued without email. data is the invoice.
quote.createdA quote was created. data is the quote object.
quote.updatedA quote's lines or details were edited, or it was moved back to draft.
quote.sentA quote was marked sent.
quote.acceptedA quote was marked accepted.
quote.declinedA quote was marked declined.
quote.expiredA sent quote passed its expiry date.
quote.invoicedA quote was converted into an invoice (data.invoice is set; invoice.created is sent too).
credit_note.createdA credit note was created. data is the credit note object.
credit_note.issuedA credit note was issued (sent right after credit_note.created when it is created as issued).
credit_note.appliedCredit was applied to an invoice.
credit_note.refundedCredit was paid back: against a payment, by scheduled payout, or recorded manually.
credit_note.voidedA credit note was voided.
payout.scheduledA payout was scheduled. data is the payout object (no bank details).
payout.submittedThe payout was sent to Netcash in a batch.
payout.paidThe batch was loaded and the action date reached.
payout.failedNetcash rejected the payout or the upload failed (data.failureReason).
payout.cancelledA scheduled payout was cancelled.
customer.payment_method.addedA customer saved a card. data is the card. See Saved card and account standing events.
customer.payment_method.removedA saved card was removed.
customer.payment_method.expiringA saved card expires within 30 days (once per card).
customer.standing.changedA customer's account standing changed (grace started, locked, unlocked, resolved).
subscription.activatedThe first payment of a subscription completed. See Subscription events.
subscription.chargedA renewal collection completed.
subscription.payment_failedA renewal collection failed.
subscription.cancelledThe subscription was cancelled (API, dashboard or gateway).
subscription.pausedThe subscription was paused (API or dashboard).
subscription.resumedA paused subscription was resumed (API or dashboard).
subscription.createdA customer subscription was created (dashboard, API, checkout or portal). See Customer subscription events.
subscription.renewedA customer subscription's renewal was paid, or an overdue payment was recovered (recovered: true).
subscription.trial_endedA customer subscription's trial ended; the first charge is issued.
subscription.past_dueA customer subscription payment failed and dunning started.
subscription.plan_changedA customer subscription moved to another plan or quantity.
subscription.updatedMetadata, externalReference or the billing date changed, or a cancellation at period end was scheduled or withdrawn.
subscription.expiredA customer subscription ended on its own: fixed term completed, first payment never arrived, or dunning set to expire.
checkout.completedA checkout session completed: paid, or started a trial or free plan. data is the checkout session (object: "checkout_session").
checkout.failedA checkout session's payment failed or was cancelled. data is the checkout session. Nothing is sent when a session expires.
eft.proof_receivedProof of payment was uploaded for an EFT order. data is the EFT order.
eft.rejectedStaff rejected the proof. data is the EFT order (with rejectionReason).
eft.expiredAn EFT order expired unpaid. data is the EFT order.
eft.cancelledAn EFT order was cancelled through the API or the dashboard. data is the EFT order.
reconciliation.completedA reconciliation run finished. data: runId, status, exceptions, lineCount, statementDate, totals, account (Netcash account and its gateways) and summary (matched, unmatched, notReceived, balance view).
webhook.testNot 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#

POST body
{
  "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"
  }
}
Event fields
FieldTypeDescription
idrequiredstringUnique event ID (evt_…). The same event sent to several endpoints, retried or resent keeps the same ID. Use it to de-duplicate.
typerequiredstringEvent type, see Events.
createdrequiredstring (date-time)ISO 8601 UTC time the event was created.
data.referencerequiredstringPayment reference. Look it up with GET /api/v1/transactions/{reference}.
data.statusrequiredstringTransaction status when the event was created.
data.amountrequirednumberGross amount in major units.
data.currencyrequiredstringISO 4217 code.
data.typerequiredstringonce, recurring, invoice, debit_order or eft.
data.gatewayrequiredstringGateway type, e.g. payfast.
data.sandboxrequiredbooleantrue 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.providerRefrequiredstring | nullThe gateway's own payment ID.
data.paymentLinkIdrequiredstring | nullPayment link the payment was made through.
data.externalReferencerequiredstring | nullThe payment link's (or EFT order's) externalReference, i.e. your order ID.
data.eftOrderIdrequiredstring | nullEFT order the payment belongs to (Manual EFT).
data.invoicerequiredobject | null{ id, number, status, externalReference } when the payment is for an invoice.
data.customerrequiredobject | null{ id, externalReference } of the paying customer.
data.metadatarequiredobjectThe payment link's (or EFT order's) metadata; {} when none.
data.renewalrequiredbooleanTrue for later collections of a subscription.
data.parentReferencerequiredstring | nullFor renewals: reference of the first payment.
data.subscriptionIdrequiredstring | nullSubscription started by the payment link, if any.
data.refundedAmountrequirednumberTotal refunded so far (excluding failed refunds); 0 if none.
data.paidAtrequiredstring | nullWhen 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:

subscription.charged
{
  "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"
  }
}
  • periodStart is when the payment was made; periodEnd adds one billing interval. For payment_failed both are null, because no period was paid.
  • subscription.cancelled, subscription.paused and subscription.resumed carry the subscription only, with no payment or 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.

Customer subscription event fields
EventExtra fields in data
activated, renewedtransactionId, invoiceId of the payment; renewed adds recovered: true when an overdue payment was recovered.
payment_failedtransactionId, invoiceId, reason
past_duereason, attempt
plan_changedpreviousPlan: { id, name }, previousAmount
updatedcancelAtPeriodEnd (and endsAt) when a cancellation at period end was scheduled or withdrawn
cancelled, expiredreason

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:

Finance event payloads
EventsdataSame as
invoice.created, .sent, .paid, .partially_paid, .cancelledInvoice objectGET /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 detailsGET /api/v1/payouts/{id}
quote.accepted (data shortened)
{
  "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"
  }
}
  • data is built when the event is created, so it reflects the record at that moment. One action can send several events (e.g. quote.invoiced and invoice.created, or credit_note.applied and invoice.paid); de-duplicate on the event id and use data.updatedAt to 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's creditNote tells 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#

Webhook request headers
HeaderValue
Content-Typeapplication/json
User-AgentCentraPoint-Webhooks/1.0
CentraPoint-EventThe event type, e.g. payment.complete.
CentraPoint-DeliveryID of this delivery (constant across its retries; a manual resend gets a new delivery ID but the same event id).
CentraPoint-Signaturet=<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:

Signature
v1 = hex( HMAC-SHA256( key = signing secret, message = "<t>." + <raw request body> ) )
  1. Read the raw request body exactly as received. Do not parse and re-serialise the JSON first.
  2. Split CentraPoint-Signature on , and read t and v1.
  3. Reject the request if t is more than 5 minutes away from your current time (protects against replay). Keep your server clock in sync.
  4. Compute the HMAC with your signing secret, used as-is including the whsec_ prefix (it is not base64-decoded), over t, a dot, and the raw body.
  5. Compare with v1 using 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 per data.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.amount and data.currency against 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.test event 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 id and 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.