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.

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.

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.

Retry Behavior

Webhook delivery retries use exponential backoff.

A failed delivery may be retried up to 10 times over an approximate 24-hour period.

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 the required timeout period
• Return an HTTP 2xx response when processing is successful

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

Best Practices

• 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