Skip to main content

Receive payment notifications

Webhook availability is pending

Endpoint management and merchant webhook delivery remain pending availability. Do not make payment fulfillment depend on them. Use server-side Checkout retrieval/polling for payment confirmation, and consult API availability before enabling webhook delivery. Enable the receiver below only after confirming account and environment support.

A webhook is a prompt to retrieve a resource, not an order fulfillment instruction. After delivery becomes available, keep resource reconciliation running so delayed or missed notifications cannot strand orders. The complete reference defines endpoint attributes, management requests, errors, event fields, signatures, and retries.

Confirm payments through retrieval today​

Keep your Checkout ID with the merchant order when creating it. On your server, retrieve that Checkout and compare its current state with the expected order, amount, and currency. A browser return URL or customer success screen is not server confirmation. Only fulfill after the authoritative resource reaches your accepted success state, using an idempotent business action.

This example requires Bash/zsh and curl. Set PAYMENTS_API_ORIGIN to your account's documented HTTPS environment origin without a trailing slash, INVISI_API_KEY to a server-only API key for that environment, and CHECKOUT_ID to the Checkout returned by creation. Do not log headers containing the key.

: "${PAYMENTS_API_ORIGIN:?Set the documented merchant API HTTPS origin}"
: "${INVISI_API_KEY:?Set the server-side key for that environment}"
: "${CHECKOUT_ID:?Set the original Checkout ID}"
curl --fail-with-body --silent --show-error \
"${PAYMENTS_API_ORIGIN}/v1/checkouts/${CHECKOUT_ID}" \
-H "Authorization: Bearer ${INVISI_API_KEY}"

See Checkout API for exact fields and transitions. Schedule bounded server-side polling with backoff; an HTTP error or pending state must not count as success. On application recovery, retrieve saved open Checkouts and paginate List Checkouts to reconcile omissions. Resource retrieval can show a newer state than an earlier notification.

Prepare a durable event inbox​

When the webhook product is enabled for your account and environment, register a publicly reachable server URL using the endpoint contract. Live endpoints require HTTPS. Each endpoint has its own secret; store the entire creation response secret securely on your server. List and update responses do not return it. Use the original idempotency key and unchanged request for an uncertain creation retry.

The intended receive flow is:

  1. Capture a size-bounded raw request body before JSON middleware changes it. Read the documented Invisi-Signature header and verify using that endpoint's full secret.
  2. Parse the authenticated body and validate the event envelope. A Thin Event contains id, type, related_object.id, related_object.type, and created_at.
  3. In a durable transaction, insert an event-inbox record unique to the merchant/environment and event id, retaining enough data for asynchronous work. An in-memory set does not survive a crash or coordinate replicas. A previously durably accepted duplicate is already received.
  4. Return 2xx promptly after durable acceptance, including duplicates. If persistence fails, do not acknowledge success. Resource retrieval and fulfillment run asynchronously.
  5. The worker retrieves the identified resource with the correct server-side account credentials, checks the merchant order mapping and current state, then performs an idempotent fulfillment or refund-accounting action. Retry local processing failures through your own durable work queue.

Event deduplication and business idempotency protect different boundaries: several distinct events can concern the same order, and polling can race with a notification. Enforce the business action's uniqueness at the order/payment level, using durable state and your fulfillment system's idempotency support. This guide does not supply a database inbox, queue, or fulfillment implementation.

Verify the exact raw bytes​

Download the dependency-free Node.js verifier. It requires Node.js 20 or later and uses only built-in node:crypto.

Pass a Buffer of the raw body, the Invisi-Signature header string, and the endpoint secret. It parses t=<unix_seconds>,v1=<lowercase_hex>, signs the exact t + "." + raw_body bytes using HMAC-SHA256, compares equal-length signatures with timingSafeEqual, and accepts timestamps within 300 seconds in both directions. It fails closed on malformed or duplicated components, unknown fields, invalid hex, unsafe timestamps, missing secret, a parsed body, or a signature mismatch. It targets this documented header; do not substitute a different header from an unrelated implementation.

Use the entire secret string, including whsec_ if present, without decoding it. JSON reserialization changes the signed bytes. Reject invalid signatures before storing or processing an event, and keep the server clock synchronized. The helper verifies authenticity and freshness only; event validation, replay deduplication, durable acceptance, and business authorization remain application responsibilities.

This is a partial receiver integration fragment after your framework has collected a bounded raw Buffer. The variables come from your HTTP request and secret store; do not place a global JSON parser in front of this operation:

import { verifyWebhook } from './verify-webhook.mjs';

// rawBody: Buffer; signatureHeader: request's Invisi-Signature value;
// endpointSecret: complete secret from secure server configuration.
if (!verifyWebhook({ rawBody, signatureHeader, secret: endpointSecret })) {
// Reject this HTTP request without accepting the event.
throw new Error('Webhook verification failed');
}
const event = JSON.parse(rawBody.toString('utf8'));
// Next: validate envelope -> durable inbox insert -> 2xx -> async worker.

Run an offline signed fixture​

Save the downloaded helper as verify-webhook.mjs in an empty working directory. Run this command there with Node.js 20+. It uses a deliberately public, synthetic secret and a fixed clock, performs no network request, and prints true, then false. Do not use the fixture secret or fixed clock in a real receiver.

node --input-type=module <<'JS'
import { verifyWebhook } from './verify-webhook.mjs';
const rawBody = Buffer.from('{"id":"evt_local","type":"checkout.succeeded","related_object":{"id":"checkout_local","type":"checkout"},"created_at":"2027-01-15T08:00:00Z"}\n');
const fixture = {
rawBody,
secret: 'whsec_local_fixture_only',
signatureHeader: 't=1800000000,v1=9517bb307d48742fdb59ad626cb4c64f6bb218438a50e16cfbf874924050ba48',
nowSeconds: 1800000000,
};
console.log(verifyWebhook(fixture));
console.log(verifyWebhook({ ...fixture, rawBody: Buffer.from('{}') }));
JS

Handle retries, delay, and missed events​

The documented contract has a five-second delivery timeout. Connection failures, timeouts, non-2xx responses, and redirects trigger retry; redirects are not followed. Retry intervals increase for up to three days after first delivery. Disabling or deleting an endpoint stops automatic delivery, but in-flight requests can still arrive. Before enabling delivery, confirm your target environment supports these signature and retry rules.

Repeated deliveries preserve event ID and body while refreshing the delivery timestamp and signature. An old created_at can accompany a fresh delivery signature. Reject stale signatures by delivery time; deduplicate by event ID. Do not reject a legitimate delayed event solely because its event creation time is old. Events can arrive out of order, so never apply notification order as resource state order.

Use related_object.type to select GET /v1/checkouts/{id} or the pending Refund API. Do not treat a Refund event as a Checkout or infer refund completion from request creation. Webhook delivery failures do not alter payment/refund state. Acknowledged events with failed worker processing need merchant-side retries; the platform stops automatic redelivery after 2xx.

Before enabling live delivery​

Confirm endpoint management and delivery are actually opened for your environment and account, and validate the documented header/signature/retry behavior end to end. Exercise invalid bodies/signatures, both clock-skew directions, duplicate events, out-of-order arrival, receiver downtime, persistence failure, worker failure, and recovery through Checkout polling. Keep test/live secrets, keys, inbox namespaces, and resource IDs separate. Monitor oldest unprocessed event and pending order age, and retain an operational path for query-based reconciliation.