Webhook Topic Definitions

Overview

This page provides detailed definitions for each supported Webhooks topic. Topics are logical groupings of related events that clients can subscribe to for real-time updates. Understanding these definitions helps ensure your subscriptions align with your business needs.

How Topics Work

Each topic represents a category of events tied to a specific entity (e.g., Transfers, Transactions). Clients can subscribe at:

Topic-level: Receive all events under a topic.
Event-level: Subscribe to specific event types.
Combination: Mix topic and event-level subscriptions for granular control.

Topic Naming Convention

Webhook topic names defined below correspond directly to the path appended to your registered base URL:

{base_url}/{topic}

Example: [https://example.com/webhooks/transfers](https://example.com/webhooks/transfers)

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

Topic Definitions

Transfers

Transfer Initiated: A transfer has been created.
Transfer Status Changed: The status of a transfer has been updated.
RTP Settlement: An instant payment transfer has reached settlement.

Transactions

Transaction Created: A transaction record has been generated.
Transaction Status Updated: The transaction status has changed.

Synthetic Accounts

Account Created: A synthetic account has been created.
Status Changed: The account status has changed.
Name Updated: The account name has been updated.

Virtual Reference Numbers (VRNs)

VRN Created: A new VRN has been issued.
Instant Payment Rail Registration Status Changed: The registration status has changed.

Customers (Beta)

Status Changed: A customer’s status has changed.
Locked: A customer’s account access has been locked.
Unlocked: A customer’s account access has been unlocked.

Debit Cards (Beta)

Requested: A card has been requested.
Issued: A card has been issued.
Status Updated: The card status has changed.
Reissued: A card has been reissued.
Locked: A card has been locked.
Unlocked: A card has been unlocked.
PIN Changed: A card PIN has been changed.
PIN Staging Failed: A card PIN staging step has failed.
PIN Commit Failed: A card PIN commit step has failed.

Example Payloads

Each webhook event includes:

event_type (e.g., created, status_change)
details object with relevant data
Unique event_id for idempotency
HMAC signature in the X-Signature header

Example:

{
  "event_type": "created",
  "details": {
    "customer_uid": "ab12cd34ef56gh78",
    "transfer_uid": "Zb12cd34ef56gh7X",
    "usd_transfer_amount": "321.00"
  }
}