Simulate Webhook

Fire a synthetic card webhook in sandbox at your configured callback URL to verify receivers end-to-end without real card activity.

Auth & Scope

HMAC authentication (standard /api auth)

Requires an active organisation

Sandbox only — the route is pinned to sandbox via middleware; the downstream org-service also refuses non-sandbox requests as a second line of defence

Simulate card webhookPOST/api/cards/:card_id/simulate-webhook

Request

Issue a POST with the card_id and the event_type you want to replay in the body.

Simulate Card Webhook

Path Parameters

card_idstringRequired

The unique identifier of the card to simulate the webhook for.

Body Parameters

card_idstringRequired

The unique identifier of the card to simulate the webhook for.

event_typestringRequired

Which card event to simulate. Must be one of the allowed values listed below.

Allowed values: authorization, settlement, reversal, decline.

Body Parameters

Response

A successful call returns 200 OK and queues a synthetic webhook against the card's configured callback URL.

Response Fields

successBoolean

Whether the simulation request was accepted.

messageString

Human-readable status message.

event_typeString

The fully-qualified webhook event type that was simulated (e.g. 'virtualcard.transaction.authorization').

referenceString

Unique reference for the simulated event, prefixed by event kind (e.g. 'SIMULATE_AUTH_<uuid>').

callback_urlString

The target callback URL the webhook was queued against, partially masked.

dispatchedBoolean

True when the synthetic webhook was actually sent. False when delivery was skipped.

skip_reasonString

Present only when 'dispatched' is false. Explains why delivery was skipped (e.g. no callback URL is configured on the card).

timestampString

ISO-8601 timestamp of the response.

Errors

400 Bad Request — missing card_id, invalid body, or event_type not in the allowed set.

403 Forbidden — called outside sandbox (enforced upstream + downstream).

gRPC Service Error — standard gRPC-mapped errors from the organisation service.

Response Body

Notes for Integrators

companyId is derived from the authenticated session — callers cannot target another tenant.

Fires a synthetic outbound webhook at the card's configured callback URL so receivers can be verified end-to-end without real card activity.