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 Transfer Queued
RTP Settlement

Topic Path:

/webhook/transfer

Transaction

Events related to financial transactions.

Example events include:

Transaction Created
Transaction Status Updated

Topic Path:

/webhook/transaction

📘
Note
RTP Receive notifications are delivered through Transaction Status Updated events.
There is not a standalone RTP Receive webhook event.

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 Note
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.

RTP Queue Lifecycle

Certain RTP transfers may enter a temporary queued state before reaching a final outcome.

flowchart TD
    A[Created] --> B[Queued]
    B --> C[Settled]
    B --> D[Failed]

Topic Details & Examples

Transfer

Category	Event Name	Trigger	Topic Name
Transfer	Transfer Initiated	A transfer has been initiated.	/transfer

{
  "event_type": "created",
  "details": {
    "customer_external_uid": "A5B4C6F9h51j2j3j",
    "customer_uid": "ab12cd34ef56gh78",
    "transfer_uid": "Zb12cd34ef56gh7X",
    "external_uid": "client-transfer-12345",
    "transaction_uid": "nYesn8dcge49Dqgm",
    "transaction_uids": ["nYesn8dcge49Dqgm"],
    "usd_transfer_amount": "321.00",
    "destination_customer_external_uid": "A5B4C6F9h51j2j3j",
    "destination_customer_uid": "ab12cd34ef56gh78"
  }
}

Category	Event Name	Trigger	Topic Name
Transfer	Transfer Status Changed	The status of a transfer has been updated.	/transfer

{
  "event_type": "status_change",
  "details": {
    "customer_external_uid": "rb12cd34ef56ghd4",
    "customer_uid": "Zb12cd34ef56gh7X",
    "new_status": "settled",
    "old_status": "pending",
    "transfer_uid": "fb12cd34ef563gq2",
    "external_uid": "client-transfer-12345",
    "usd_transfer_amount": "321.00",
    "transaction_uid": "s8J7J6J5J5h31A28",
    "transaction_uids": ["s8J7J6J5J5h31A28"],
    "destination_customer_external_uid": "rb12cd34ef56ghd4",
    "destination_customer_uid": "Zb12cd34ef56gh7X"
  }
}

Category	Event Name	Trigger	Topic Name
Transfer	RTP Transfer Queued	An RTP transfer has entered queue processing.	/transfer

{
  "event_type": "transfer_queued",
  "details": {
    "customer_external_uid": "rb12cd34ef56ghd4",
    "customer_uid": "Zb12cd34ef56gh7X",
    "queued_until": "2026-08-13T06:18:31.332Z",
    "status": "queued",
    "transfer_uid": "fb12cd34ef563gq2",
    "external_uid": "client-transfer-12345",
    "transaction_uids": [
      "s8J7J6J5J5h31A28"
    ],
    "usd_transfer_amount": "321.00",
    "destination_customer_external_uid": "rb12cd34ef56ghd4",
    "destination_customer_uid": "Zb12cd34ef56gh7X"
  }
}

Category	Event Name	Trigger	Topic Name
Transfer	RTP Settlement	An `instant_payment` Transfer has reached settlement. Please note this is a separate event than a Transfer or Transaction's status update events.	/transfer

{
  "event_type": "rtp_settlement",
  "details": {
    "customer_external_uid": "9vZz5Up4YzVXWpEY",
    "customer_uid": "X3wrzgf4Hkg1fdqt",
    "transfer_uid": "S3s16vP4iTjmVKde",
    "external_uid": "client-transfer-12345",
    "usd_transfer_amount": "321.00",
    "transaction_uid": "4kpBYX7UkQEJ4WUt",
    "transaction_uids": ["4kpBYX7UkQEJ4WUt", "MyhsiAUo4jgfbEF9"],
    "destination_synthetic_account_uid": "UWniK6K7w83TFzBr",
    "destination_customer_external_uid": "customer_defined_uid",
    "destination_customer_uid": "dXDxCgpvxWd4GW48",
    "network_transaction_id": "202602020430000961BAAAA00041250796"
  }
}

📘
Note

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

A queued transfer may subsequently transition to:

RTP Settlement

Transfer Status Changed (Failed)

Transaction

Category	Event Name	Trigger	Topic Name
Transaction	Transaction Created	A transaction record has been created.	/transaction

{
  "event_type": "created",
  "details": {
    "asset_breakdown": [
      {
        "asset_quantity": "-5.0",
        "asset_type": "USD",
        "synthetic_account_uid": "y3mgbw9CdzMWa2m7",
        "us_dollar_amount": "-5.00"
      }
    ],
    "customer_external_uid": "business-partner-unique-identifier-27",
    "customer_uid": "zK7DSmQiqFVue624",
    "description": "Received RTP Payment",
    "destination_synthetic_account_uid": "hpqbJpevVzafUc1T",
    "net_asset": "positive",
    "network_transaction_id": "202602020430000961BAAAA00041250796",
    "new_status": "created",
    "settled_at": null,
    "settled_index": null,
    "source_synthetic_account_uid": "y3mgbw9CdzMWa2m7",
    "transfer_uid": "fb12cd34ef563gq2",
    "transaction_uid": "c2c7Kws8cR8ZCBLn",
    "type": "instant_payment",
    "us_dollar_amount": "5.00",
    "virtual_reference_number_uid": null
  }
}

Category	Event Name	Trigger	Topic Name
Transaction	Transaction Status Updated	The status of a transaction has been updated.	/transaction

{  
"event_type": "updated",  
"details": {  
  "asset_breakdown":[  
  {  
     "asset_quantity": "-5.0",  
     "asset_type": "USD",  
     "synthetic_account_uid": "zoPodA7UtHKm9APD",    
     "us_dollar_amount": "-5.00"  
   },  
 ],  
  "customer_external_uid": "business-partner-unique-identifier-8",  
  "customer_uid": "gXjG87TQEUmsdVSg", 
  "description": "Received RTP Payment",    
  "destination_synthetic_account_uid": "phBEeJ4CN8EVuBAU", 
  "net_asset":"positive",  
  "new_status": "pending",  
  "settled_at": null,
  "settled_index": null,  
  "source_synthetic_account_uid": "zoPodA7UtHKm9APD", 
  "transfer_uid": "fb12cd34ef563gq2",  
  "transaction_uid": "exJmgX7ABWX4DFU4",  
  "type": "instant_payment",  
  "us_dollar_amount": "5.00",  
  "virtual_reference_number_uid": null 
 }  
}

Synthetic Account

Category	Event Name	Trigger	Topic Name
Synthetic Account	Synthetic Account Created	A synthetic account record has been created.	/synthetic-account

{ 
"event_type": "created", 
"details": { 
  "external_uid": "client-generated-id", 
  "customer_uid": "mRJMrhj97MlfPLkdgk", 
  "status": "active", 
  "synthetic_account_category": "general", 
  "synthetic_account_uid": "6NrMNrdB4hVHDXbx", 
  "pool_owner_customer_uid": "mRJMrhj97MlfPLkdgk", 
  "pool_uid": "i4wGvRybCiqg3Zhc", 
  "routing_number": "123456789" 
 } 
}

Category	Event Name	Trigger	Topic Name
Synthetic Account	Synthetic Account Status Changed	The status of a synthetic account has been updated.	/synthetic-account

{
  "event_type": "status_change",
  "details": {
    "additional_info": {
      "message": "Cannot create Synthetic Account; Synthetic Account could not be created"
    },
    "external_uid": "client-generated-id",
    "customer_uid": "pLJM7hjs7MqfDknvh",
    "new_status": "failed",
    "old_status": "initiated",
    "synthetic_account_category": "wire_external",
    "synthetic_account_uid": "6NrMNrdB4hVHDXbx"
  }
}

Category	Event Name	Trigger	Topic Name
Synthetic Account	Synthetic Account Name Updated	The name of a Synthetic Account has been updated.	/synthetic-account

{
  "event_type": "name_updated",
  "details": {
    "additional_info": null,
    "external_uid": "client-generated-id",
    "customer_uid": "pLJM7hjs7MqfDknvh",
    "new_status": "active",
    "old_status": "active",
    "synthetic_account_category": "wire_external",
    "synthetic_account_uid": "6NrMNrdB4hVHDXbx"
  }
}

Virtual Reference Numbers (VRNs)

Category	Event Name	Trigger	Topic Name
VRNs	VRN Created	Sent after a VRN is created	/virtual-reference-number

{  
"event_type": "created",  
"details": {  
  "external_uid": "client-generated-id",  
  "virtual_reference_number_uid": "mRJMrhj97MlfPLkdgk",   
  "status": "active",  
  "instant_payment_rail_registration_status": "pending",  
  "synthetic_account_uid": "6NrMNrdB4hVHDXbx",  
  "virtual_reference_number_last_four": "5624",  
  "routing_number": "123456789"  
 }  
}

Category	Event Name	Trigger	Topic Name
VRNs	VRN Instant Payment Rail registration status change	The status of a VRN's Instant Payment Rail registration has been updated.	/virtual-reference-number

{  
"event_type": "instant_payment_status_change",  
"details": {  
  "external_uid": "client-generated-id",  
  "virtual_reference_number_uid": "mRJMrhj97MlfPLkdgk",  
  "status": "active",    
  "new_instant_payment_rail_registration_status": "archived",  
  "old_instant_payment_rail_registration_status": "unregistered"  
 }  
}

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.