Overview

This guide explains how to subscribe to Newline Webhooks, register endpoints, configure topic delivery, and manage webhook subscriptions.

Webhooks allow clients to receive real-time event notifications through HTTPS endpoints.

Webhook delivery is topic-based and URL-driven. Clients subscribe to topics and Newline delivers events to topic-specific endpoints derived from the subscribed topic name.

Subscription Model

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

Webhook routing is topic-path based. Events are delivered to the endpoint associated with the subscribed topic path.

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 the standard format:

{base_url}/webhook/{topic-path}

Where:

• base_url is provided during onboarding
• /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.

Registration Process

To subscribe to Webhooks:

1. Contact Newline Onboarding Support (NOS).
2. Provide:
   • A secure HTTPS base URL
   • A public encryption key
3. Select the topics and/or events you would like to receive.
4. Define the desired subscription model:
   • Topic-level
   • Event-level
   • Combination
5. Complete onboarding and validation activities as directed by Newline.

Topic Selection Guidance

During onboarding, clients should identify:

• Topics they wish to receive
• Specific event types, if event-level filtering is desired
• Sandbox topics required for integration testing
• Production topics required for live processing

Webhook Delivery

Newline publishes webhook events to predefined topics.

Examples include:

• Transfer-related events
• Transaction lifecycle events
• Synthetic account events
• Virtual reference number events

Events are delivered to the endpoint associated with the subscribed topic path.

For example:

https://example.com/webhook/transfer

may receive transfer-related events based on the configured subscription.

RTP Queue Subscription Example

Clients that wish to receive queue-processing notifications should subscribe to the Transfer topic and monitor the following events:

• transfer_queued
• status_change
• rtp_settlement

Queue Processing Considerations

When a transfer enters queue processing, a transfer_queued event is published.

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

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

Possible outcomes include:

• RTP Settlement
• Transfer Status Changed (Failed)

Queue Lifecycle

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

Retry Behavior

Webhook delivery retries use exponential backoff.

A failed webhook delivery may be retried up to 10 times if a successful HTTP 2xx response is not received.

Retry Schedule

Important Notes

• Retry timing follows an exponential backoff pattern.
• Any HTTP 2xx response is considered a successful delivery and stops all remaining retry attempts.
• Newline supports up to 10 retry attempts per webhook notification.
• When 10 retries are configured, delivery attempts may continue for approximately 34 hours and 6 minutes after the initial delivery attempt.

Success Handling

Any HTTP 2xx response is considered a successful delivery.

Failure Handling

Any HTTP 4xx or 5xx response is considered a failed delivery and is eligible for retry according to the configured retry schedule.

Delivery Requirements

Webhook endpoints must:

• Be accessible via HTTPS
• Accept POST requests
• Respond within 5 seconds whenever possible
• Return an HTTP 2xx response when processing is successful

Responses that exceed the timeout threshold may be treated as delivery failures and can trigger retry processing.

Failure to meet these requirements may result in retries according to the retry policy.

Best Practices

RTP Queue Testing

Before enabling queue-related processing in production, clients should validate handling of:

• transfer_queued
• RTP Settlement
• Failed transfer outcomes

Recommended sandbox test scenarios:

• queue_then_settle
• queue_then_fail

Verify that applications correctly handle queue lifecycle events and final transfer outcomes.

• Validate webhook signatures before processing payloads
• Process webhook requests asynchronously when possible
• Return a success response promptly after receiving an event
• Monitor endpoint availability and response times
• Ensure topic-specific endpoints remain available for delivery