Guides
Learn More about Newline
Start typing to search…

Topics

Overview

Newline’s Webhooks system delivers real-time event notifications grouped into topics. Each topic represents a category of related events, such as transfers, transactions, or account updates. Clients can subscribe to these topics to receive messages relevant to their business workflows.

Supported Topics & Definitions

Here are the currently supported Webhooks topics, along with definitions:

Transfers

Events related to money movement between accounts.

  • 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 settled.

Transactions

Events related to financial transactions.

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

Synthetic Accounts

Events related to virtual accounts used for managing funds.

  • 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)

Events related to instant payment identifiers.

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

Webhook Payload Encryption

“All webhook payloads are encrypted in transit. Below are unencrypted examples provided for reference and clarity, and you’ll need to decrypt them to view the actual data. This is applicable to both production and sandbox environments.

  • One encrypted example payload for the Transaction Created event
  • Unencrypted example payloads for all other events—these are for illustrative purposes only, and are not representative of what you’ll receive in production.

Encrypted Example

This payload is exactly as sent over the wire in production.

{
  "event_type": "created",
  "details": "-----BEGIN PGP MESSAGE-----\n\nhF4DFxtzJPLaKAUSAQdAT9RPEWzHJYBPCX2yxycUQguFtbiAPGA9/gMLmTPdoxYw\n4Aph17vyDm1JNvf1HpS4rhUyz3d09q7dRb23YBf958N3R9hlnTlwcrMpiuRQ0IUP\n0sCkAe9JQFlONsLtPSuDqaJbkj2swJPPGIRf+NXDltwUbaUjtZtDF+2gmaNgqZvb\n7oa8Rji+47aytUVKegh4m8lbpAZoQ92Ix/oGHZ8JG5wKQ3JAGivmlcxHnAsNnkom\nhjmM99wZD03+hVgQP2rpXV0+fOQk5DoRoY5dsaKgLhP5MNOpjUWvSymhuEf/k5cy\nV55vjKycatg3K8FF+DTE/2l/8KdXBle5E55p6hILfWm35WuOwhVBhwpqU5pkP570\nmv1+V1Q0bHh68zqQwUqbW4SyPxwSQtWnlOEnIG7lCr6eqKkxkiKTVKNWBcLspUbC\nZ17+v/xc8QoqKXc9r3g4RmIiSZ+Cf3TWnWknx+OCwHN/nmTCuGN0qh9F+pkiI88k\nj0YQ4aR/XozVngrpeM7Bpz78ENX/Wv6hGKaECsDTTz4ZWVMes7xsKMsncKAJAMuH\nckj3ShScvG61dnL2/8awi5lU+5vKxtk=\n=0FAk\n-----END PGP MESSAGE-----\n"

Note: All webhook payloads are encrypted in transit. Below are unencrypted examples provided for reference and clarity; these are not identical to production payloads.

Topic Details & Examples

Below you’ll find topic-specific details and illustrative payload examples. Remember, all actual webhook events are encrypted in production and sandbox environments—you’ll need to decrypt them to access the real data.

Transfer Initiated

CategoryEvent NameTriggerTopic Name
TransferTransfer InitiatedA transfer has been initiated.<client>.<env>.transfer

Unencrypted Example - Transfer Initiated


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

Transfer Status Changed

CategoryEvent NameTriggerTopic Name
TransferTransfer Status ChangedThe status of a transfer has been updated.<client>.<env>.transfer

Unencrypted Example - Transfer Status Changed


{
  "event_type": "status_change",
  "details": {
    "customer_external_uid": "rb12cd34ef56ghd4",
    "customer_uid": "Zb12cd34ef56gh7X",
    "new_status": "settled",
    "old_status": "pending",
    "transfer_uid": "fb12cd34ef563gq2",
    "transaction_uid": "s8J7J6J5J5h31A28",
    "transaction_uids": [
      "s8J7J6J5J5h31A28"
    ],
    "destination_customer_external_uid": "rb12cd34ef56ghd4",
    "destination_customer_uid": "Zb12cd34ef56gh7X",
    "failure_reason": "Unable to initiate instant payment transfer.", 
    "failure_code": "ERR001", 
    "network_transaction_id": "202512040430000961BAAAA00041250796",
    "virtual_reference_number_uid": "4KGty9ycWNcGFo6R"
  }
}

RTP Settlement

CategoryEvent NameTriggerTopic Name
TransferRTP SettlementAn instant_payment Transfer has reached settlement. Please note this is a separate event than a Transfer or Transaction's status update events.<client>.<env>.transfer

Unencrypted Example – RTP Settlement


{
  "event_type": "rtp_settlement",
  "details": {
    "customer_external_uid": "business-partner-unique-identifier-8",
    "customer_uid": "gXjG87TQEUmsdVSg",
    "transfer_uid": "fb12cd34ef563gq2",
    "transaction_uid": "exJmgX7ABWX4DFU4",
    "transaction_uids": [
      "exJmgX7ABWX4DFU4"
    ],
    "destination_synthetic_account_uid": "phBEeJ4CN8EVuBAU",
    "destination_customer_external_uid": "rb12cd34ef56ghd4",
    "destination_customer_uid": "Zb12cd34ef56gh7X",
    "network_transaction_id": "202512040430000961BAAAA00041250796",
    "virtual_reference_number_uid": 
  }
}
📘

Note

Please note that account balances update when a Transfer's status updates. The above event notes settlement, which occurs immediately prior to the status being updated. If interested in being updated of account balance update, subscribe to the status change events.

Transaction Created

CategoryEvent NameTriggerTopic Name
TransactionTransaction CreatedA transaction record has been created.<client>.<env>.transaction

Unencrypted Example – Transaction Created

{
  "event_type": "created",
  "details": {
    "adjustment_uid": null,
    "customer_uid": "szaxXExVVScwKqPT",
    "created_at": "2025-12-04T07:07:07.707Z",
    "custodial_account_uids": [
      "s5DQw78BKi5ye7CX",
      "EffzWWZztHo4B3XM"
    ],
    "description": "Sent RTP ID 20231004043000096P1BAAAA00041250796 to Rupert's Roofers of Raleigh",
    "destination_synthetic_account_uid": "smfVbCVA4iqHUkUX",
    "id": 39,
    "initial_action_at": "2025-12-04T07:07:07.707Z",
    "net_asset": "negative",
    "new_status": "queued",
    "old_status": null,
    "return_uid": null,
    "settled_at": "2025-12-04T09:07:07.707Z",
    "settled_index": 10,
    "source_synthetic_account_uid": "H2uQrLRNAfQr3WLn",
    "statement_posted_at": "2019-10-17T00:01:53.682Z",
    "transaction_batch_uid": "3",
    "transaction_event_uids": [
      "TzqSj2r6NN5MMYu9"
    ],
    "transfer_uid": null,
    "type": "instant_payment",
    "uid": "7PpuQuEz9FR8VeQt",
    "us_dollar_amount": "13500.45",
    "virtual_reference_number_uid": "rdPjBZeKfpGZgaT1",
    "instant_payment": {
      "memo": "For the 6/5/23 shipment of pineapple popsicles",
      "network_transaction_id": "20231004043000096P1BAAAA00041250796"
    }
  }

Transaction Status Updated

CategoryEvent NameTriggerTopic Name
TransactionTransaction Status UpdatedThe status of a transaction has been updated.<client>.<env>.transaction

Unencrypted Example – Transaction Status Updated

{
  "event_type": "updated",
  "details": {
    // same as create
  }
}

Synthetic Account Created

CategoryEvent NameTriggerTopic Name
Synthetic AccountSynthetic Account CreatedA synthetic account record has been created.<client>.<env>.synthetic_account

Unencrypted Example – Synthetic Account Created

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

Synthetic Account Status Changed

CategoryEvent NameTriggerTopic Name
Synthetic AccountSynthetic Account Status ChangedThe status of a synthetic account has been updated.<client>.<env>.synthetic_account

Unencrypted Example – Synthetic Account Status Changed

{
  "event_type": "status_change",
  "details": {
    "additional_info": {
      "message": "error message; additional_info could be null",
    },
    "customer_uid": "pLJM7hjs7MqfDknvh",
    "external_uid": "client-generated-id",
    "new_status": "failed",
    "old_status": "initiated",
    "synthetic_account_category": "wire_external",
    "synthetic_account_uid": "6NrMNrdB4hVHDXbx"
  }
}

Synthetic Account Name Update

CategoryEvent NameTriggerTopic Name
Synthetic AccountSynthetic Account Name UpdatedThe name of a Synthetic Account has been updated.<client>.<env>.synthetic_account

Unencrypted Example – Synthetic Account Name Updated

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

Virtual Reference Numbers (VRN) Created

CategoryEvent NameTriggerTopic Name
VRNsVRN Instant Payment Rail registration status changeThe status of a VRN's Instant Payment Rail registration has been updated.<client>.<env>.virtual_reference_number

Unencrypted Example – VRN Created

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

Virtual Reference Numbers (VRN) Instant Payment Rail Registration Status Changed

CategoryEvent NameTriggerTopic Name
VRNsVRN Instant Payment Rail registration status changeThe status of a VRN's Instant Payment Rail registration has been updated.<client>.<env>.virtual_reference_number

Unencrypted Example – VRN Instant Payment Rail Registration Status Changed

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

Best Practices

Now that you’ve seen example payloads, here are best practices for implementing webhook events securely and reliably.

  • Subscribe only to topics relevant to your workflows.
  • Confirm topic names with your Newline Specialist during onboarding.
  • Implement idempotency using event IDs.
  • Validate HMAC signatures for each event.

Related Pages

🚧

Upcoming Feature Preview This feature is currently not available for client use. However, we're excited to share a preview of the functionality that will be introduced.

  • Transaction Created
  • Transaction Updated
  • Transfer Status Changed
  • RTP Settlement
  • Synthetic Account Status Changed

Updated 6 days ago