Overview

Use Newline Webhooks to receive near-real-time event notifications at your HTTPS endpoint without managing message queue infrastructure.

Delivery is topic-based and URL-driven: each subscribed topic is delivered to a dedicated endpoint path derived from its name. Each delivery includes an HMAC signature that you can validate to check the payload’s integrity and authenticity.

What Are Webhooks?

Webhooks deliver event notifications directly to your HTTPS endpoints in near real time. Use this push-based model when you need immediate event visibility and prefer an integration pattern that does not require 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 an HTTPS endpoint, encryption key, and topic subscription.
• Signature Validation: HMAC signatures enable you to verify message authenticity and integrity.

Retry Behavior

Failed deliveries are automatically retried.

Webhook deliveries may be retried up to 10 times if a successful 2xx response is not received.

For testing purposes:

• Retry 9 occurs approximately 17 hours after the original delivery attempt.
• Retry 10 occurs approximately 34 hours after the original delivery attempt.

Any successful 2xx response stops additional retry attempts.

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 endpoint path determines delivery routing.

The event_type field identifies the event contained within the payload but does not determine which endpoint receives the event.

For example:

• All Transfer events are delivered to /webhook/transfer.
• All Transaction events are delivered to /webhook/transaction.

Inspect the event_type field to determine how to process events received within a topic. Depending on your use case, inspect the payload to distinguish between events within the same 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.
• Configure your endpoint to process duplicate deliveries without creating duplicate effects.
• Return a 2xx response as soon as your endpoint has successfully received the event.
• Configure your endpoint to respond 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 34 hours
  • Retry 9: ~17 hours
  • Retry 10: ~34 hours

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

Retry Testing

Webhook retry functionality can be validated by temporarily making the receiving endpoint unavailable and generating a qualifying event.

A common testing approach is:

1. Disable the webhook endpoint.
2. Generate an event.
3. Allow retry attempts to occur.
4. Re-enable the endpoint before the final retry attempt.
5. Verify successful event delivery.

Refer to individual event documentation for supported testing scenarios.