Clients are responsible for implementing secure API endpoints to receive and process webhook events for each topic they subscribe to. These endpoints must be capable of:
Receiving HTTPS POST requests
Validating HMAC signatures
Responding within 5 seconds to avoid retries
Clients can use any programming language or framework to build their webhook handlers.
Below is a list of webhook topics currently supported by Newline. These topics are opt-in and can be selected based on your application’s needs—whether for internal operations or customer-facing features.
Current topics include:
Transfer
Category Event Name Trigger Topic Name Transfer Transfer Initiated A transfer has been initiated. <client>.<env>.transfer
Payload
{
"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"
}
}
Category Event Name Trigger Topic Name Transfer Transfer Status Changed The status of a transfer has been updated. <client>.<env>.transfer
Payload
{
"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"
}
}
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. <client>.<env>.transfer
Payload
{
"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"
}
}
📘 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
Category Event Name Trigger Topic Name Transaction Transaction Created A transaction record has been created. <client>.<env>.transaction
Payload
{
"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",
"debit_card_uid": "gdgN9zmH6PTfzgUe",
"denial_reason": "insufficient_funds",
"description": "description",
"destination_synthetic_account_uid": "hpqbJpevVzafUc1T",
"net_asset": "negative",
"new_status": "denied",
"settled_index": null,
"source_synthetic_account_uid": "y3mgbw9CdzMWa2m7",
"transfer_uid": "fb12cd34ef563gq2",
"transaction_uid": "c2c7Kws8cR8ZCBLn",
"type": "atm_withdrawal",
"us_dollar_amount": "5.00",
"ach_return_code": null
}
}
Category Event Name Trigger Topic Name Transaction Transaction Status Updated The status of a transaction has been updated. <client>.<env>.transaction
Payload
{
"event_type": "updated",
"details": {
"asset_breakdown":[
{
"asset_quantity": "-5.0",
"asset_type": "USD",
"synthetic_account_uid": "zoPodA7UtHKm9APD",
"us_dollar_amount": "-5.00"
},
{
"asset_quantity": "0.25",
"asset_type": "LPL",
"synthetic_account_uid": "phBEeJ4CN8EVuBAU",
"us_dollar_amount": "5.00"
}
],
"customer_external_uid": "business-partner-unique-identifier-8",
"customer_uid": "gXjG87TQEUmsdVSg",
"debit_card_uid": "QeaBfr63HSb3pReT",
"denial_reason": null,
"description": "description",
"destination_synthetic_account_uid": "phBEeJ4CN8EVuBAU",
"net_asset":"neutral",
"new_status": "pending",
"settled_index": null,
"source_synthetic_account_uid": "zoPodA7UtHKm9APD",
"transfer_uid": "fb12cd34ef563gq2",
"transaction_uid": "exJmgX7ABWX4DFU4",
"type": "atm_withdrawal",
"us_dollar_amount": "5.00",
"ach_return_code": null
}
}
Synthetic Account
Category Event Name Trigger Topic Name Synthetic Account Synthetic Account Created A synthetic account record has been created. <client>.<env>.synthetic_account
Payload
{
"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. <client>.<env>.synthetic_account
Payload
{
"event_type": "status_change",
"details": {
"additional_info": {
"message": "error message; additional_info could be null",
},
"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. <client>.<env>.synthetic_account
JSON
{
"event_type": "name_updated",
"details": {
"additional_info": nil,
"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 <client>.<env>.virtual_reference_number
Payload
{
"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. <client>.<env>.virtual_reference_number
Payload
{
"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"
}
}
Customer
Category Event Name Trigger Topic Name Customer Customer Status Changed Sent any time a customer's status is updated <client>.<env>.customer
JSON
{
"event_type": "status_change",
"details": {
"customer_uid": "A1B2C3D48I7H6G5F",
"external_uid": "h5B7h11M89Yt6R54",
"new_status": "approved",
"prior_status": "manual_review"
}
}
Category Event Name Trigger Topic Name Customer Customer Locked A customer is locked <client>.<env>.customer
JSON
{
"event_type": "lock",
"details": {
"customer_uid": "A1B2C3D48I7H6G5F",
"external_uid": "h5B7h11M89Yt6R54"
}
}
Category Event Name Trigger Topic Name Customer Customer Unlocked A customer is unlocked <client>.<env>.customer
JSON
{
"event_type": "unlock",
"details": {
"customer_uid": "A1B2C3D48I7H6G5F",
"external_uid": "h5B7h11M89Yt6R54"
}
}
Debit Card
Category Event Name Trigger Topic Name Debit Card Debit Card Requested A customer has requested a new debit card for an account <client>.<env>.debit_card
JSON
{
"event_type": "requested",
"details": {
"card_artwork_uid": "HLGMh9M67zBLRm5y",
"card_last_four": "1243",
"customer_uid": "A7A7b8b85D3D3D3D",
"debit_card_uid": "jfidKFgdiPogem6B",
"external_uid": "2E2D2E3W4e5r6t7y",
"pool_uid": "AbCdEfGh12983874",
}
}
Category Event Name Trigger Topic Name Debit Card Debit Card Issued A debit card has been issued <client>.<env>.debit_card
JSON
{
"event_type": "issued",
"details": {
"card_artwork_uid": "HLGMh9M67zBLRm5y",
"card_last_four": "1243",
"customer_uid": "A7A7b8b85D3D3D3D",
"debit_card_uid": "jfidKFgdiPogem6B",
"external_uid": "2E2D2E3W4e5r6t7y",
"pool_uid": "AbCdEfGh12983874",
}
}
Category Event Name Trigger Topic Name Debit Card Debit Card Status Updated The status of a debit card has been updated <client>.<env>.debit_card
JSON
{
"event_type": "status_change",
"details": {
"card_artwork_uid": "HLGMh9M67zBLRm5y",
"card_last_four": "3421",
"customer_uid": "Q9A7b8b85D3D3D3D",
"debit_card_uid": "jfidKFgdiPogem6B",
"external_uid": "H7A7b8b85D3D5D3E",
"new_status": "normal",
"pool_uid": "4E2D2E3W4e5r6t7y",
"prior_status": "shipped",
"ready_to_use": "true"
}
}
Category Event Name Trigger Topic Name Debit Card Debit Card Reissued A debit card re-issue has been requested <client>.<env>.debit_card
JSON
{
"event_type": "reissue_requested",
"details": {
"card_artwork_uid": "HLGMh9M67zBLRm5y",
"card_last_four": "3421",
"customer_uid": "Q9A7b8b85D3D3D3D",
"debit_card_uid": "jfidKFgdiPogem6B",
"external_uid": "H7A7b8b85D3D5D3E",
"reason": "damaged",
"pool_uid": "4E2D2E3W4e5r6t7y"
}
}
Category Event Name Trigger Topic Name Debit Card Debit Card Locked A debit card is locked <client>.<env>.debit_card
JSON
{
"event_type": "lock",
"details": {
"debit_card_uid": "jfidKFgdiPogem6B",
"external_uid": "H7A7b8b85D3D5D3E"
}
}
Category Event Name Trigger Topic Name Debit Card Debit Card Unlocked A debit card is unlocked <client>.<env>.debit_card
JSON
{
"event_type": "unlock",
"details": {
"debit_card_uit": "jfidKFgdiPogem6B",
"external_uid": "H7A7b8b85D3D5D3E"
}
}
Category Event Name Trigger Topic Name Debit Card Debit Card PIN Changed A debit card's PIN is successfully changed <client>.<env>.debit_card
JSON
{
"event_type": "pin_changed",
"details": {
"card_artwork_uid": "HLGMh9M67zBLRm5y",
"card_last_four": "3421",
"customer_uid": "Q9A7b8b85D3D3D3D",
"debit_card_uid": "jfidKFgdiPogem6B",
"external_uid": "H7A7b8b85D3D5D3E",
"pool_uid": "4E2D2E3W4e5r6t7y"
}
}
Category Event Name Trigger Topic Name Debit Card Debit Card PIN Staging Failed The initial step to update a debit card's PIN has failed <client>.<env>.debit_card
JSON
{
"event_type": "pin_staging_failed",
"details": {
"card_artwork_uid": "HLGMh9M67zBLRm5y",
"card_last_four": "3421",
"customer_uid": "Q9A7b8b85D3D3D3D",
"debit_card_uid": "jfidKFgdiPogem6B",
"external_uid": "H7A7b8b85D3D5D3E",
"pool_uid": "4E2D2E3W4e5r6t7y"
}
}
Category Event Name Trigger Topic Name Debit Card Debit Card PIN Commit Failed The final step to update a debit card's PIN has failed <client>.<env>.debit_card
JSON
{
"event_type": "pin_commit_failed",
"details": {
"card_artwork_uid": "HLGMh9M67zBLRm5y",
"card_last_four": "3421",
"customer_uid": "Q9A7b8b85D3D3D3D",
"debit_card_uid": "jfidKFgdiPogem6B",
"external_uid": "H7A7b8b85D3D5D3E",
"pool_uid": "4E2D2E3W4e5r6t7y"
}
}
Webhook topic names follow this structure:
For example:
abc-enterprise.sandbox.transaction
Newline will work with clients to define and confirm topic names during onboarding.
Each webhook event includes:
A topic name
An event_type (e.g., created, status_change)
A details object with relevant data
A unique event ID (for idempotency)
An HMAC signature in the header
Each topic includes multiple event types. Below are examples for key topics:
Transfer
Transfer Initiated Transfer Status Changed RTP Settlement
Topic: <client>.<env>.transfer
JSON
{
"event_type": "created",
"details": {
"customer_external_uid": "A5B4C6F9h51j2j3j",
"transfer_uid": "Zb12cd34ef56gh7X",
"usd_transfer_amount": "321.00"
}
}
