Overview

Use this page to select webhook topics and interpret the events delivered for each topic.

Webhook topics are logical groupings of related events that you can subscribe to for real-time updates.

How a Webhook Topic Works

Each topic represents a category of events tied to a specific entity.

Examples include:

Transfer
Transaction
Synthetic Account
Virtual Reference Number
Customer
Debit Card

Subscription Models

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.

Subscription Examples

Subscription Type	Topic	Events Received
Topic-Level	Transfer	All Transfer events
Event-Level	Transfer	RTP Settlement only
Combination	Transfer	All Transfer events
Combination	Transaction	Transaction Status Updated only

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.

Examples:

Transfer Topic: /webhook/transfer
Transaction Topic: /webhook/transaction
Virtual Reference Number Topic: /webhook/virtual-reference-number

Topic Naming Convention

Webhook endpoints follow the 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

Topic names are defined by Newline and cannot be customized by clients.

Topic Definitions

Topic	Description	Supported Events
Transfer	Events related to money movement between accounts.	Transfer Initiated, Transfer Status Changed, RTP Transfer Queued, RTP Settlement
Transaction	Events related to transaction lifecycle activity.	Transaction Created, Transaction Status Updated
Synthetic Account	Events related to synthetic account management and maintenance.	Synthetic Account Created, Synthetic Account Status Changed, Synthetic Account Name Updated
Virtual Reference Number	Events related to virtual reference number creation, registration, and maintenance.	VRN Created, Instant Payment Rail Registration Status Changed
Customer	Events related to customer lifecycle and customer record activity.	Customer Status Changed, Customer Locked, Customer Unlocked
Debit Card	Events related to debit card issuance, status changes, and lifecycle activity.	Debit Card Requested, Debit Card Issued, Debit Card Status Updated, Debit Card Reissued, Debit Card Locked, Debit Card Unlocked, Debit Card PIN Changed, Debit Card PIN Staging Failed, Debit Card PIN Commit Failed

Event Definitions

Event Name	Event Type	Description
Transfer Initiated	`created`	Generated when a transfer has been successfully created.
Transfer Status Changed	`status_change`	Generated whenever a transfer transitions from one status to another.
RTP Transfer Queued	`transfer_queued`	Generated when RTP queueing places a transfer into a queued state prior to final settlement or failure.
RTP Settlement	`rtp_settlement`	Generated when an RTP transfer reaches final settlement.

Consumer Expectations

Receipt of a transfer_queued event does not indicate that transfer processing has completed.

Queued transfers may subsequently:

Move to pending and continue through normal RTP processing
Reach rtp_settlement
Reach a failed status if RTP processing remains unavailable until the queued_until timestamp is reached

Clients should continue monitoring transfer events until a final outcome is received.

Transaction Events

Event Name	Event Type	Description
Transaction Created	`created`	Generated when a transaction record is first created.
Transaction Status Updated	`updated`	Generated whenever a transaction transitions from one status to another.

RTP Receive notifications are delivered through Transaction Status Updated events. Newline does not provide a standalone RTP Receive webhook event.

Synthetic Account Events

Event Name	Event Type	Description
Synthetic Account Created	`created`	Generated when a synthetic account is successfully created.
Synthetic Account Status Changed	`status_change`	Generated when a synthetic account status changes.
Synthetic Account Name Updated	`name_updated`	Generated when a synthetic account name is updated.

Virtual Reference Number (VRN) Events

Event Name	Event Type	Description
VRN Created	`created`	Generated when a Virtual Reference Number is created.
Instant Payment Rail Registration Status Changed	`instant_payment_status_change`	Generated when a VRN's instant payment registration status changes.

Customer Events

Event Name	Event Type	Description
Customer Status Changed	`status_change`	Generated when a customer status changes.
Customer Locked	`lock`	Generated when a customer is locked.
Customer Unlocked	`unlock`	Generated when a customer is unlocked.

Debit Card Events

Event Name	Event Type	Description
Debit Card Requested	`requested`	Generated when a new debit card is requested.
Debit Card Issued	`issued`	Generated when a debit card is issued.
Debit Card Status Updated	`status_change`	Generated when a debit card status changes.
Debit Card Reissued	`reissue_requested`	Generated when a debit card reissue is requested.
Debit Card Locked	`lock`	Generated when a debit card is locked.
Debit Card Unlocked	`unlock`	Generated when a debit card is unlocked.
Debit Card PIN Changed	`pin_changed`	Generated when a debit card PIN is successfully updated.
Debit Card PIN Staging Failed	`pin_staging_failed`	Generated when the initial PIN update stage fails.
Debit Card PIN Commit Failed	`pin_commit_failed`	Generated when the final PIN update stage fails.

Payload Field Definitions

Transfer Fields

Field	Type	Description
`external_uid`	string	Client-supplied identifier used for transfer tracking and reconciliation.
`usd_transfer_amount`	string	Transfer amount in U.S. dollars.
`transfer_uid`	string	Unique identifier assigned to the transfer.
`transaction_uid`	string	Primary transaction identifier associated with the transfer.
`transaction_uids`	array	Collection of transaction identifiers associated with the transfer.
`customer_external_uid`	string	Client-defined identifier for the originating customer.
`customer_uid`	string	Internal unique identifier for the originating customer.
`destination_customer_external_uid`	string	Client-defined identifier for the destination customer.
`destination_customer_uid`	string	Internal unique identifier for the destination customer.

Queue Fields

Field	Type	Description
`queued_until`	string	Timestamp indicating when a queued transfer will be failed if RTP processing remains unavailable. The value is based on the transfer creation time plus the queue retention period configured for the program.
`status`	string	Current queue status. The expected value for queue events is `queued`.

Transaction Fields

Field	Type	Description
`transaction_uid`	string	Unique identifier assigned to the transaction.
`new_status`	string	Current status of the transaction.
`settled_index`	integer \| null	Settlement sequence number if applicable.

RTP Settlement Fields

Field	Type	Description
`network_transaction_id`	string	Unique identifier assigned by the RTP or FedNow network.
`destination_synthetic_account_uid`	string	Unique identifier of the destination synthetic account.

Subscription Guidance

When selecting a webhook topic:

Subscribe only to topics relevant to your business workflow.
Use topic-level subscriptions when all events within a topic are required.
Use event-level subscriptions when only specific events are required.
Use a combination subscription model to support more granular delivery requirements.

Endpoint Routing Examples

A subscription to the Transfer topic may result in delivery to:

https://example.com/webhook/transfer

A subscription to the Virtual Reference Number topic may result in delivery to:

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

Regardless of whether a client subscribes at the topic level or event level, events are delivered to the endpoint associated with the topic path.

The event_type value identifies the event contained in the payload, while the topic path determines the delivery endpoint.

Examples:

Transfer Topic: /webhook/transfer
Transaction Topic: /webhook/transaction
Virtual Reference Number Topic: /webhook/virtual-reference-number