Skip to content

Webhooks

A webhook is an HTTP request Invoise sends to your server when a payment changes. You can start with GET status checks and add webhooks when you need automatic updates.

Terminal window
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/webhooks' \
-H 'Authorization: Bearer ivk_...' \
-H 'Idempotency-Key: <saved-unique-key>' \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com/invoise","filters":["transfer","invoice","payout"]}'

Use your own public HTTPS URL. Local and private addresses are rejected. Save the secret returned when the endpoint is created: you need it to verify requests.

A shop can have up to 10 endpoints. An endpoint’s URL can be changed, so reuse one instead of adding another. See Limits.

Event Meaning
transfer.observed A transfer was seen; it is not confirmed yet.
transfer.confirmed An incoming transfer has enough confirmations. It may be only a partial invoice payment.
transfer.reverted A previous transfer event was reversed.
invoice.closed The invoice closed on chain.
invoice.cancelled The checkout was cancelled or the invoice expired; this is not a refund.
payout.sent The payout was broadcast or its outgoing transfer was seen.
payout.confirmed Complete settlement accounting is available.
payout.reverted A previous payout confirmation was reversed.
payout.failed A terminal payout failure needs intervention.

For invoice.cancelled, data.reason says why: expired when the invoice lifetime ran out, merchant_blocked when Invoise staff blocked the merchant. A cancellation by the merchant, including one caused by archiving the shop, has no reason.

An empty filters list receives every event. Otherwise list groups (transfer, invoice, payout), single event types such as payout.confirmed, or both. Incoming transfers and outgoing payouts are different events. A temporary RPC or gas delay is not payout.failed.

gas.wait and sweep.failed are accepted as filters, but Invoise does not send them to your endpoint. They are internal signals: gas.wait means a payout is waiting for network fee funds and continues on its own; sweep.failed means an attempt to move the funds to your recipient failed. You need no action for either. A payout that cannot complete reaches you as payout.failed.

In a sandbox shop you can simulate both through POST /shops/{shop_id}/sandbox/simulate to check that a delayed payout does not break your flow. They change the payout’s state only and send no webhook.

Invoise-Signature has the form t=<timestamp>,v1=<hex>. The signature is HMAC-SHA256 of timestamp + "." + raw_body, using your webhook secret.

The following Node.js example also rejects timestamps more than five minutes from the server clock. Keep that clock synchronised and choose your tolerance deliberately.

import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, header, secret) {
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header ?? '');
if (!match) return false;
const [, timestamp, signature] = match;
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!Number.isFinite(age) || age > 300) return false;
const expected = createHmac('sha256', secret)
.update(timestamp + '.')
.update(rawBody)
.digest();
return timingSafeEqual(Buffer.from(signature, 'hex'), expected);
}

Pass the original request bytes as rawBody. Do not parse JSON and stringify it before checking the signature. Reject invalid signatures before storing or acting on their contents.

A transfer.confirmed body looks like this. The schema of every event is in the webhooks section of openapi.json.

{
"id": "<event-id>",
"type": "transfer.confirmed",
"created_at": "2026-09-19T10:00:05Z",
"data": {
"issuance_id": "<issuance-id>",
"public_id": "<public-id>",
"shop_id": "<shop-id>",
"external_id": "customer-42",
"type": "deposit",
"family": "evm",
"chain_id": 8453,
"token": "<token-address>",
"token_decimals": 6,
"address": "<payment-address>",
"recipient": "<recipient-address>",
"invoice_cancelled": false,
"cancelled_at": null,
"direction": "incoming",
"chain_event": {
"event_id": "<transfer-id>",
"kind": "transfer.confirmed",
"chain_id": 8453,
"tx_hash": "<tx-hash>",
"log_index": 2,
"block_number": 35123456,
"block_hash": "<block-hash>",
"token": "<token-address>",
"from": "<payer-address>",
"to": "<payment-address>",
"amount": "25000000",
"confirmations": 12,
"occurred_at": "2026-09-19T10:00:00Z"
}
}
}

To credit a payment, read data.chain_event. amount is what arrived, in token base units: divide it by 10^data.token_decimals, so 25000000 with 6 decimals is 25 tokens. event_id identifies the transfer and tx_hash is its transaction. data.issuance_id and data.external_id name the invoice or deposit it paid. For an invoice, one transfer can be a partial payment.

Case Handling
Duplicates Deduplicate using Invoise-Event-ID, which matches the envelope’s id. Save the ID and the business update atomically.
Accepting an event Save accepted events durably, return 2xx promptly, and process queued work afterwards.
Retries and replays Retries and manual replays repeat the event ID. Invoise-Attempt-ID changes and is not a deduplication key.
Headers Each request carries Invoise-Event-ID and Idempotency-Key, both equal to the event id; Invoise-Delivery-ID, one per event and endpoint; Invoise-Attempt-ID, new on every attempt; and Invoise-Signature.
Event order Events can arrive out of order. Use their contents and reconcile against current status when needed.

If a chain reorganisation removes a transfer, transfer.reverted arrives with chain_event.reference_event_id equal to the event_id of the transfer you credited: take that amount back. payout.confirmed carries amount, what the recipient received, and service_fee, the fee taken from this payout; in payout.sent and payout.failed both are null. Every payout event has a stable payout_id and the transaction hash. incoming_transfer_ids lists the transfers the payout covered, at most 100; incoming_transfers_truncated flags a longer list.

Older stored events may use project_id; read shop_id first and fall back to it if needed. Replays keep the original bytes.

GET /api/v1/shops/{shop_id}/deposits is the complete journal of confirmed incoming transfers of the shop, for invoices and deposits alike, newest first. It is not a list of addresses: POST on the same path creates a deposit address. Each row has id, equal to chain_event.event_id from the webhook, and issuance_id, external_id, amount, tx_hash, sender and occurred_at. Page through it with limit and cursor to catch up after downtime or to check your records.

status in the journal is always confirmed. A transfer reverted by a reorganisation disappears from the journal, and you receive transfer.reverted for it.

A delivery succeeds when your endpoint answers with any 2xx status. Another status, a timeout or a connection error is retried: the first retry comes 5 seconds later, and the wait doubles after each attempt up to one hour between attempts. After 72 hours without a 2xx, Invoise stops and marks the delivery failed.

Each attempt has 20 seconds in total, and your response headers must arrive within 10 seconds. Store the event and answer first; do the work afterwards.

Archiving a shop with PATCH /api/v1/shops/{shop_id} and {"archived":true} disables its webhook endpoints. The shop’s events, including the invoice.cancelled of its unpaid invoices, are still recorded but not delivered.

List GET /api/v1/shops/{shop_id}/deliveries. Replay a delivery with POST /api/v1/shops/{shop_id}/deliveries/{id}/replay and a saved idempotency key. Replaying does not create a new business event. A replay starts a new 72-hour retry window; a delivered or failed delivery can be replayed.