Overview

Newline’s Webhooks system delivers real-time event notifications grouped by topic. Each topic represents a category of related events, such as transfers, transactions, account updates, or virtual reference number activity.

Webhook delivery is topic-based and URL-driven.

How does a Webhook Topic Work?

Each webhook topic represents a logical grouping of related events.

For example:

The transfer topic includes events related to money movement.
The transaction topic includes events related to transaction lifecycle activity.
The synthetic_account topic includes events related to synthetic account management.
The virtual_reference_number topic includes events related to virtual reference number creation and registration activity.

Clients can subscribe using one of the following models.

Topic-Level

Receive all events associated with a topic.

Event-Level

Receive only selected events within a topic.

Combination

Mix topic-level and event-level subscriptions to support more granular event delivery requirements.

Routing Behavior

Webhook delivery routing is topic-based.

Events are delivered to the endpoint associated with the subscribed topic path regardless of subscription type.

The event_type field identifies the event contained within the payload but is not used to determine the delivery endpoint.

Endpoint Structure

Webhook endpoints follow a standardized URL format:

{base_url}/webhook/{topic-path}

Where:

base_url is provided by the client
/webhook is a required path segment
topic-path is derived from the subscribed topic

Examples

https://example.com/webhook/transfer

https://example.com/webhook/virtual-reference-number

Event Routing

Webhook delivery routing is determined by the endpoint path associated with the subscribed topic.

Examples:

/webhook/transfers

/webhook/transactions

/webhook/synthetic-accounts

/webhook/virtual-reference-numbers

The event_type field identifies the event that occurred but should not be used as the routing mechanism.

Depending on the use case, payload inspection may be required when distinguishing between multiple events delivered through the same topic endpoint.

Supported Topics

Transfer

Events related to money movement between accounts.

Example events include:

Transfer Initiated
Transfer Status Changed
RTP Settlement

Topic Path:

/webhook/transfer

Transaction

Events related to financial transactions.

Example events include:

Transaction Created
Transaction Status Updated

Topic Path:

/webhook/transaction

Synthetic Account

Events related to synthetic account management.

Example events include:

Account Created
Status Changed
Name Updated

Topic Path:

/webhook/synthetic-account

Virtual Reference Number

Events related to virtual reference number activity.

Example events include:

VRN Created
Instant Payment Rail Registration Status Changed

Topic Path:

/webhook/virtual-reference-number

Webhook Payload Encryption

All webhook payloads are encrypted in transit in both Sandbox and Production environments.

The examples contained throughout this guide are provided for illustration only and are not representative of the encrypted payload delivered over the wire.

Production webhook deliveries contain encrypted payload data that must be decrypted using the client-provided encryption key.

This guide includes:

One encrypted example payload demonstrating the actual transport format
Unencrypted examples for readability and reference only

Important

All actual webhook deliveries are encrypted.

The unencrypted examples shown throughout this guide are intended only to help clients understand payload structure and event contents.

Topic Details & Examples

Important

Webhook routing is based on the endpoint path associated with the subscribed topic.

The event_type field identifies the event that occurred but does not determine routing.

Clients should use the endpoint path as the primary routing mechanism and inspect payload contents when additional event differentiation is required.