Overview

Newline’s Webhooks system provides a push-based mechanism for delivering real-time event notifications over HTTPS. It is designed for clients who require immediate event delivery without the operational overhead of managing message queue infrastructure.

Webhook delivery is topic-based and URL-driven. Each subscribed topic is delivered to a dedicated endpoint path derived from the topic name.

Webhooks are secured using HMAC signatures to ensure payload integrity and authenticity.

What Are Webhooks?

Webhooks allow Newline to deliver event notifications directly to your HTTPS endpoints in near real time. This push-based model is ideal for clients that require immediate event visibility and prefer a simpler integration pattern than message queues.

Each webhook event is delivered to a topic-specific endpoint following a standardized URL structure:

{base_url}/webhook/{topic-path}

Where:

• base_url is provided by the client
• /webhook is a required path segment
• topic-path is derived from the subscribed topic name

Examples:

https://example.com/webhook/transfer

https://example.com/webhook/virtual-reference-number

https://webhook-tester.client.com/record/fifththird/test/webhook/transfer

Key Features

• Push Delivery: Events are delivered directly to your HTTPS endpoint.
• Topic-Based Routing: Events are routed using topic-specific endpoint paths.
• Simple Setup: Requires only a secure HTTPS endpoint, encryption key, and topic subscription.
• Automatic Retry Logic: Failed deliveries are retried using exponential backoff for up to 10 attempts over approximately 24 hours.
• Secure Delivery: HMAC signatures allow clients to verify message authenticity and integrity.

Endpoint Routing

Webhook routing is based on the endpoint URL path associated with the subscribed topic.

Topic paths use the following transformation rules:

• Topic names are singular
• Underscores (_) are replaced with hyphens (-)
• Topic names are not otherwise modified

Examples:

The event_type field identifies the event that occurred but should not be used as the primary mechanism for determining topic routing. Depending on the use case, payload inspection may be required to distinguish between different events within a topic.

Getting Started

To begin using Webhooks, follow these steps:

1. Review authentication requirements. Learn how to validate webhook signatures and secure your endpoint in Webhook Authentication.

2. Understand available topics and endpoint path conventions in Webhook Topics.

3. Review detailed topic definitions and supported events in Webhook Topic Definitions.

4. Configure subscriptions and register your endpoint using Webhook Subscriptions.

5. Validate receipt and processing of test events in Sandbox before enabling production delivery.

Best Practices

• Validate HMAC signatures for every webhook event.
• Implement idempotency using the unique event identifier included with each event.
• Ensure your endpoint can safely process duplicate deliveries.
• Return a 2xx response as soon as the event has been successfully received.
• Ensure your endpoint responds within 5 seconds.
• Monitor webhook delivery success rates and investigate repeated failures.
• Test all routing, decryption, validation, and event-processing logic in Sandbox prior to production use.

Delivery Behavior

Webhook delivery success is determined by the HTTP response code returned by your endpoint:

Failed deliveries are retried using exponential backoff:

• Maximum retries: 10
• Retry duration: Approximately 24 hours
• Retry termination: Any successful 2xx response

After the retry window is exhausted, the event is considered undeliverable.