Webhooks - Incard Developer API

Incard can notify your systems over HTTPS when activity occurs on the platform. You register endpoints in the Incard dashboard. This guide covers how to receive and verify transaction webhook deliveries.

How it works

Setup
Someone with permission to manage webhooks adds an HTTPS URL in the Incard dashboard, chooses which events to receive, and saves the signing secret when it is shown. That secret is what your server uses to confirm deliveries really came from Incard. When a webhook event happens
If the event matches what that endpoint subscribed to, Incard sends a signed POST to your URL with a JSON body and X-Incard-* headers. Your server should verify the signature on the raw body, process the event once (using the event id for deduplication), and return 2xx if you accepted it. If verification fails, respond with 4xx. If your server errors or times out, Incard may retry the delivery a limited number of times with incrementally increasing delays.

Configure in the dashboard

Outbound webhooks can be managed in the Incard web app — under Settings → Webhooks. Each endpoint has its own URL, signing secret, and list of subscribed event types.

Action	What to know
Add endpoint	Public HTTPS URL, optional description, and which event types to receive (see below).
Signing secret	Keep it safe. It will be used to verify the signature of the webhook notification.
Edit	Update URL, description, or subscribed events.
Rotate secret	Issues a new signing secret. Update your verifier immediately — the previous secret stops signing new deliveries.
Disable	Stops new deliveries; useful for maintenance or incidents.

Endpoint URL rules

Must be HTTPS with a normal public hostname.
Must be reachable from the public internet (no localhost, private IPs, or internal-only hostnames).
Maximum length 2048 characters.
Incard does not follow redirects.

Transaction event types

For transaction webhooks, subscribe per endpoint to one or both of:

Event	When it fires
`transaction.create`	A new transaction is recorded for your company.
`transaction.update`	An existing transaction changes (for example status or amounts).

You only receive types you subscribed to. Each POST body includes the event type in JSON and in the X-Incard-Event-Type header.

Transaction webhook request format

Each transaction delivery is a POST with Content-Type: application/json. Headers

Header	Purpose
`X-Incard-Event-Id`	Unique id for this notification — equals the envelope `id`. Use for idempotency.
`X-Incard-Event-Type`	`transaction.create` or `transaction.update` for this guide.
`X-Incard-Timestamp`	Unix time (seconds) when the request was signed.
`X-Incard-Signature`	`v1=` plus hex HMAC-SHA256 digest.

Body — versioned envelope:

{
    "id": "c93a7a3a-918d-4f62-ac79-c4ae64a4b8bc",
    "data": {
        "id": "342ea759-8870-418a-aa4c-ebc3a93ff70d",
        "name": "ACME Corp",
        "type": "out",
        "points": 0,
        "status": "pending",
        "user_id": "29b297ca-c617-437e-9c1d-32f494fbf44d",
        "payee_id": "6992e50e-dfd7-4d9c-891c-362ccfc01b58",
        "direction": "debit",
        "reference": "Sent from Incard",
        "account_id": "0d6c0a2a-2b08-49bc-89a9-eb936c9ff28c",
        "company_id": "bebb185d-8210-4e66-ac63-397b49a1e09f",
        "created_at": "2026-07-02T16:07:39.970773Z",
        "fee_amount": "0.00",
        "updated_at": "2026-07-02T16:07:39.970773Z",
        "base_amount": "300.00",
        "payee_route": "local",
        "authorized_at": "2026-07-02T16:07:39.942Z",
        "base_currency": "GBP",
        "account_amount": "300.00",
        "transaction_at": "2026-07-02T16:07:39.917Z",
        "account_currency": "GBP",
        "source_payment_id": "ab8861be-020f-6449-655e-c7b00ff71b74",
        "transaction_amount": "300.00",
        "transaction_currency": "GBP"
    },
    "type": "transaction.create",
    "source": "transactions",
    "occurred_at": "2026-07-02T16:07:39.970773Z",
    "schema_version": 1
}

Envelope fields

Field	Notes
`id`	Unique event id (UUID). Deduplicate on this value — safe replays should not double-apply side effects.
`type`	Event type: `transaction.create` or `transaction.update`.
`source`	Always `transactions` for these events.
`occurred_at`	RFC 3339 timestamp of when the event was produced.
`schema_version`	Envelope version. Currently `1`.
`data`	Transaction snapshot — see the fields below.

data fields The transaction snapshot is produced by the transactions service. Fields marked Always are present on every delivery; fields marked When set are omitted when they have no value, so treat them as optional. New fields may be added over time — ignore any you don’t recognise.

Field	Type	Presence	Description
`id`	string (UUID)	Always	Transaction id. Stable across `transaction.create` and later `transaction.update` events.
`name`	string	Always	Human-readable label (for example payee or merchant name).
`type`	enum	Always	Transaction type, e.g. `card`, `atm`, `out`, `in`, `fee`, `exchange_out`, `exchange_in`, `transfer_out`, `transfer_in`, `chargeback`, `reversal`, `adjustment`, `direct_debit`, `direct_credit`.
`points`	integer	When set	Loyalty points associated with the transaction.
`status`	enum	Always	Lifecycle status: `pending`, `completed`, `declined`, or `reversed`.
`user_id`	string (UUID)	When set	User who initiated the transaction.
`payee_id`	string	When set	Identifier of the payee.
`direction`	enum	Always	`debit` (money out) or `credit` (money in).
`reference`	string	When set	Free-text payment reference.
`account_id`	string (UUID)	Always	Account the transaction belongs to.
`company_id`	string (UUID)	Always	Company that owns the transaction.
`created_at`	string	Always	When the transaction record was created.
`fee_amount`	string (decimal)	When set	Fee charged for the transaction.
`updated_at`	string	Always	When the transaction record was last updated.
`base_amount`	string (decimal)	When set	Amount in the base currency.
`payee_route`	string	When set	Payment route (for example `local`).
`authorized_at`	string	When set	When the transaction was authorised.
`base_currency`	string	When set	Reporting/base currency.
`account_amount`	string (decimal)	When set	Amount in the account currency (e.g. `"300.00"`).
`transaction_at`	string	Always	When the transaction occurred.
`account_currency`	string	Always	Currency of the account.
`source_payment_id`	string	Always	Identifier of the payment in the originating source system.
`transaction_amount`	string (decimal)	When set	Amount in the transaction currency.
`transaction_currency`	string	When set	Currency the transaction was made in.

Verify the signature

Always verify before trusting the body. Use the raw request body exactly as received (before parsing JSON). Signed string:

{X-Incard-Timestamp}.{raw_body}

Expected header value:

v1=HMAC_SHA256(signing_secret, signed_string)   // lowercase hex

Compare to X-Incard-Signature with a constant-time function.

Reject requests whose timestamp is far from your server clock (for example older than five minutes).

const crypto = require("crypto");

function verifyIncardWebhook({ secret, rawBody, headers }) {
  const timestamp = headers["x-incard-timestamp"];
  const signature = headers["x-incard-signature"];
  if (!timestamp || !signature?.startsWith("v1=")) return false;

  const expected =
    "v1=" +
    crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  if (signature.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Handle transaction webhook deliveries

Recommended handler flow:

Read raw body → verify signature → parse JSON.
Skip or no-op if id was already processed.
Queue or persist work, then return 2xx promptly (within a few seconds).

Your response	Typical result
`2xx`	Success — no further retries for that attempt.
`3xx`	Redirects are not followed — counts as a failed delivery.
`4xx`	Treated as failure — generally not retried.
`5xx` / timeout / unreachable host	Retried with increasing delays (up to a small fixed number of attempts).

Do heavy processing asynchronously after responding 2xx.

Go live checklist

Dashboard: create an endpoint with production URL and the transaction event types you need.
Store signing secret securely (environment variable or secrets manager).
Deploy verifier + idempotent handler.
Return 2xx only after the event is safely recorded on your side.
Monitor failures and disable the endpoint from the dashboard if your service is down.

​How it works

​Configure in the dashboard

​Endpoint URL rules

​Transaction event types

​Transaction webhook request format

​Verify the signature

​Handle transaction webhook deliveries

​Go live checklist

How it works

Configure in the dashboard

Endpoint URL rules

Transaction event types

Transaction webhook request format

Verify the signature

Handle transaction webhook deliveries

Go live checklist