Overview

To receive event notifications via Webhooks, clients must authenticate each incoming message to verify its integrity and origin.

Webhook authentication is handled using HMAC signatures, and all webhook deliveries occur over secure HTTPS connections.

Webhook Endpoint Structure

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

{base_url}/webhook/{topic-path}

Where:

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

Examples

https://example.com/webhook/transfers

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

Prerequisites

After selecting your webhook topic and/or events during onboarding, Newline will provide:

HMAC Key

Used to generate the signature included with every webhook delivery.

Clients must provide:

Encryption Key

Used to encrypt webhook payloads before delivery.

Base URL

The HTTPS endpoint where webhook events will be delivered.

Webhook Topic and Events

The topic and/or events the client would like to subscribe to.

Secure Delivery Requirements

Webhook endpoints must:

• Use HTTPS
• Validate the X-Request-Signature-SHA-256 header
• Validate the X-Request-Signature-Timestamp header
• Respond within 5 seconds to avoid delivery failures and retries

Signature Headers

Each webhook request includes headers that can be used to validate the authenticity and integrity of the message.

Signature Header

X-Request-Signature-SHA-256

Contains the HMAC SHA-256 signature generated by Newline.

Timestamp Header

X-Request-Signature-Timestamp

Contains the timestamp used during signature generation and validation.

Clients should validate both the timestamp and signature before processing webhook payloads.

Signature Validation Process

When a webhook is received:

1. Retrieve the HMAC key issued during onboarding.
2. Read the request payload.
3. Read the signature timestamp header.
4. Reconstruct the message according to the signature validation requirements.
5. Generate an HMAC SHA-256 hash using the shared key.
6. Compare the generated signature to the value provided in the request header.
7. Process the message only if validation succeeds.

Requests that fail validation should be rejected.

Webhook Payload Encryption

All webhook payloads are encrypted prior to delivery.

Clients are responsible for:

• Maintaining a valid public encryption key
• Decrypting webhook payloads after receipt
• Protecting private keys used for decryption

Webhook payload encryption provides an additional layer of security beyond HTTPS and HMAC signature validation.

Successful Responses

To indicate successful webhook processing, endpoints should return an HTTP 2xx response.

Examples include:

200 OK
201 Created
202 Accepted
204 No Content

Any HTTP 2xx response is considered a successful delivery.

Failed Responses

Responses in the following ranges are considered failed deliveries:

4xx
5xx

Failed webhook deliveries are eligible for retry according to the configured retry policy.

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 may trigger retry processing according to the retry schedule.

Optional Health Checks

Newline supports optional health checks against a /health endpoint when one is available.

Clients are not required to implement a /health endpoint to receive webhook deliveries.

If implemented, a health endpoint may be used for:

• Connectivity validation
• Operational monitoring
• Environment readiness checks

Security Best Practices

• Always validate webhook signatures before processing payloads.
• Verify the timestamp associated with incoming requests.
• Use HTTPS for all webhook endpoints.
• Securely store HMAC keys and private encryption keys.
• Reject requests that fail signature validation.
• Process webhook requests asynchronously when possible.
• Return an HTTP 2xx response only after the request has been successfully accepted for processing.