Breadcrumbs

Webhooks

Overview

Webhooks offer a reliable and efficient way to receive real-time notifications about transactions, cards, and other supported platform events. The Webhooks section allows administrators configure endpoints, subscribe to events, and monitor deliveries. The feature uses Svix for webhook management.

Enabling the functionality

By default, the Webhook functionality is disabled in the Admin Panel. To enable it, follow the instructions below:

  • for customers: Ask your project manager (PM) to enable Webhooks for the required environment.

  • for PM: Provide the relevant environment details in Jira-task so the technical support engineer can enable the functionality.

Access to the section itself is also gated by role (ROLE_SUPER_ADMIN or ROLE_WEBHOOKS_ALL)

How to configure endpoints

Endpoints determine where webhook messages are sent. To configure an endpoint:

  1. Open Admin Panel → Webhooks in the left sidebar

  2. Navigate to the Endpoints tab in the Webhooks section;

  3. Click Add Endpoint to create a new endpoint;

  4. Enter the URL and other required details for the endpoint, such as, for example, channels;

  5. Select the event types to be associated with this endpoint;

  6. Click Save to confirm the changes.

image-20260914-155506.png

Endpoints and channels are self-service. If you need an new event type is not currently available, contact your PM.

There are two types of webhooks:

  • Platform events — normalized Crassula events, such as transaction or card updates. This is the default and covers most events.

  • Relayed provider webhooks (raw) — the original provider payload, passed through unchanged when you need the provider’s data instead of Crassula’s normalized version.

Every event follows the same shape: a top-level type field naming the event as <entity>.<status> (for example transaction.completed or issuedCard.suspended), and a key named after the entity holding the actual data (for example"transaction": {...} with all details).

Subscriptions are configured at the event level, not the status level. For example, subscribing to transaction includes transaction.completed, transaction.failed, and all other transaction statuses; the sub-status only shows up inside the payload's own type field.

Each endpoint has a signing secret. Use it to verify every incoming webhook before processing the payload.

image-20260915-055823.png

Using channels

Channels let you restrict an endpoint to webhook messages tagged for specific clients or agents by criteria, so each endpoint receives only relevant events. By default, the “channel” setting is hidden in the SVIX admin panel—which means that WL receives all hooks from all companies by default. If you need to enable it, please request it via PM.

Each webhook is automatically tagged with one or more channels. You don’t set these tags when creating events — you use them to filter which messages an endpoint receives.

Customizing channels for individual customers or agents

You can customize channels specifically for individual persons/companies or agents. This customization allows for a more targeted approach in message delivery, ensuring that notifications are relevant to the specific customer or agent.

image-20260915-060716.png

To set up a channel for a specific person/company or agent, create channels with the following naming conventions:

  • For customers: client_ID, where ID is the unique identifier of the customer. For example, client_1bd942c0-4cec-486f-be7a-7b14118ad4ad.

  • For agents: agent_ID, where ID is the unique identifier of the agent. For example, agent_32fad32d-0412-4f28-9349-a3cdca639c34.

Every message related to a given client is always tagged with that client's own client_ID channel. If the client is a company client, or is itself an agent, the message is additionally tagged with the corresponding agent_ID channel — a message can carry more than one channel at once.

Assigning a channel to an endpoint

  1. Navigate to the Endpoints tab in the Webhooks section.

  2. Click on any existing endpoint.

  3. On the right side of the opened screen, locate the Channels field.

  4. Click Edit and enter a specific ID of a person/company or an agent.

  5. Once the channel appeared in the field, click Save to to directly associate the endpoint with the respective customer or agent.

Please note, when you assign a specific ID of a person, company, or agent to a channel, the endpoint will only receive data related to that particular entity. If you do not specify a channel, the endpoint will receive data from all companies under the white label.

Event Catalog

Only predefined event types are available. If you need an new event type - please contact your PM.

Currently supported event types, their triggers, and sample payloads available in the Event Catalog tab within the Webhooks section :

Event type

Trigger

transaction

An account transaction changes state — initiated, processing, checked, approved, completed, refunded, failed, declined, or canceled.

Covers all transaction types (transfers, fees, currency exchange, card purchases/withdrawals/top-ups, cashback, interest, etc.) except interledger transactions, which are not published as webhooks, manual created transactions.

Sample payloads: transaction

{
"type": "transaction.completed",
"transaction": {
"id": "3f29e1e0-73b2-4a11-9c3e-example00001",
"type": 1,
"status": 2,
"state": 8,
"amount": "0.33",
"currency": "GBP",
"currencyType": 1,
"description": "Incoming local transfer fee",
"provider": "railsbank",
"providerType": "internal",
"providerId": null,
"partnerId": null,
"clientId": "client_id_value",
"clientName": "client_name_value",
"chargeType": null,
"processingTime": null,
"issuedCardHoldTransactionId": null,
"fromAccountIban": "GB00EXAMPLE00000000000000",
"beneficiaryAccountIban": null,
"beneficiaryAccountNumber": "12345678",
"beneficiaryName": "beneficiary_name",
"beneficiaryType": 2,
"remitterAccountNumber": "87654321",
"remitterName": "remitter_name",
"bankDetails": null,
"directDebitMandateId": null,
"directDebitPaymentId": null,
"fees": [],
"createdAt": "2025-04-16T10:43:08+00:00",
"updatedAt": "2025-04-16T10:43:14+00:00",
"settlementDate": "2025-04-16T00:00:00+00:00"
}
}

cards

  • issuedCard

 

  • card status changes — created, activated, suspended, expired, blocked, or declined

Sample payloads: issuedCard

{
"type": "issuedCard.suspended",
"issuedCard": {
"id": "card_id_value",
"status": "suspended",
"statusReason": null,
"mask": "4111 **** **** 1111",
"clientId": "client_id_value",
"cardHolder": "John Smith",
"expirationYear": 2027,
"expirationMonth": 8
}
}

  • issuedCardHoldTransaction

  • card operation “authorization” (hold) changes — usually its status or amount

Sample payloads: hold

{
"type": "issuedCardHoldTransaction.created",
"issuedCard": {
"id": "hold_id_value",
"issuedCardId": "card_id_value",
"amount": "50.00",
"currency": "GBP",
"amountChange": null,
"accountAmount": "50.00",
"accountCurrency": "GBP",
"accountAmountChange": null,
"status": "ACTIVE",
"createAt": "2025-04-16T10:43:08+00:00",
"description": "POS purchase"
}
}

  • issuedCardTopUp

  • card operation “top-up” operation is completed or declined

Sample payloads: issuedCardTopUp / issuedCardWithdrawal

Same shape for both (only the top-level key and type prefix differ):

{
"type": "issuedCardTopUp.completed",
"issuedCardTopUp": {
"transactionId": "transaction_id_value",
"providerTransactionId": "provider_transaction_id_value",
"providerCardId": "provider_card_id_value",
"status": "completed"
}
}

  • issuedCardWithdrawal

  • card operation “withdrawal” is completed or declined

  • 3dsSession

  • available only for Decta mobile 3DS session starts for a card. Per-agent setup is required — ask your PM if needed.

Sample payloads: 3dsSession

Note: unlike other events, type is always an empty string here — there's only one shape for this event, so it doesn't need a sub-status.

{
"type": "",
"3dsSession": {
"id": "ae8f5867-bfe9-4f06-9a64-9d07a594be56",
"status": "approved",
"deviceChannel": "app",
"createdAt": "2024-12-03T14:36:17+00:00",
"purchase": {
"merchant": { "...": "..." },
"amount": "100.00",
"currency": "GBP",
"at": "2024-12-03T14:36:17+00:00"
},
"card": {
"scheme": "MASTERCARD"
}
}
}

  • decta_webhook

  • available only for Decta card-issuing webhooks. All Decta cards events are relayed unchanged. Filtering by provider webhook sub-type is not supported.

    Other providers are not supported yet. If needed, contact your PM — support is added case by case, not through self-service.

For some events, you can receive the provider’s original webhook payload without any changes. This is useful if you need the provider’s native format for reconciliation or your own tools. Raw webhooks from other providers are available only on request. Contact your PM if you need support for another provider.

Security & delivery guarantees

  • Signing: every webhook is signed with a secret key. Always check the signature before processing it → it confirms that the webhook data was not changed.

  • Retries: if delivery fails, SVIX automatically tries again. Failed deliveries can also be checked and replayed from Activity → you don’t lose an event if your system is temporarily unavailable.

image-20260915-063834.png

  • Ordering: Webhooks may arrive in a different order. Use IDs and timestamps if the order is important → you should not assume that events arrive in the same order they happened.

  • Duplicates: The same webhook may be delivered more than once. Use svix-id to identify duplicates → it prevents the same event from being processed twice.

Monitoring Webhook Activity

Logs

Logs tab offers a detailed record of all webhook activities:

  1. Navigate to the Logs tab in the Webhooks section;

  2. View the log entries, which include information about successful deliveries, errors, and other relevant data.

image-20260915-060938.png

Filtering: the Logs/Activity search supports filtering deliveries by Transaction ID, Status and State out of the box. Anything beyond that (custom filters, different sort criteria) not a self-service setting, ask to your PM.

Activity

The Activity tab allows real-time monitoring of webhook events:

  1. Navigate to the Activity tab in the Webhooks section;

  2. Monitor ongoing webhook events with updates and detailed information.

Workflow

The workflow involves configuring endpoints, setting up event types, and monitoring activities through logs and real-time updates. This setup ensures effective management and tracking of all webhook activities within the Administrative Panel.