Overview

Configure your webhook endpoint to validate incoming HMAC signatures, decrypt payloads, and return responses that determine delivery retries.

Newline signs webhook deliveries with HMAC (a keyed hash used to verify a message’s integrity and origin) and sends them over HTTPS.

Webhook Endpoint Structure

Newline delivers each webhook event to a topic-specific endpoint with this URL structure:

{base_url}/webhook/{topic-path}

Where:

• base_url is the URL you register with Newline.
• /webhook is a required path segment.
• topic-path is derived from the webhook topic name.

Examples

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

Prerequisites

Complete these onboarding tasks before receiving webhooks:

1. Select the webhook topics and events you want to receive.
2. Provide a public encryption key so Newline can encrypt webhook payloads before delivery.
3. Register the HTTPS base URL for your receiving endpoint.
4. Obtain the HMAC key that Newline issues for signature validation.

Delivery Requirements

Configure your webhook endpoint to:

• Use HTTPS.
• Validate the X-Request-Signature-SHA-256 header.
• Validate the X-Request-Signature-Timestamp header.
• Respond within 5 seconds.

Newline may treat requests that exceed the response threshold as failed deliveries and retry them according to the configured retry policy.

Signature Headers

Each webhook request includes headers you use to validate the message’s authenticity and integrity.

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.

Validate both the timestamp and signature before processing a webhook payload.

Example Headers

X-Request-Signature-SHA-256: abc123...
X-Request-Signature-Timestamp: 2026-08-06T17:21:32Z

Validate a Signature

When you receive a webhook:

1. Retrieve the HMAC key issued during onboarding.
2. Read the request payload.
3. Read the X-Request-Signature-Timestamp header.
4. Read the X-Request-Signature-SHA-256 header.
5. Reconstruct the signed message.
6. Generate an HMAC SHA-256 hash with the shared key.
7. Compare the generated signature with the signature in the request header.
8. Reject the request if validation fails.
9. Process the webhook only after validation succeeds.

Webhook Payload Encryption

Newline encrypts all webhook payloads before delivery.

You are responsible for:

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

Payload encryption provides additional protection beyond HTTPS and HMAC signature validation.

Respond to Deliveries

Return an HTTP 2xx response after your endpoint has accepted the webhook for processing. The following responses indicate a successful delivery:

200 OK
201 Created
202 Accepted
204 No Content

Newline considers any HTTP 2xx response successful and stops further retry attempts. HTTP 4xx and 5xx responses are failed deliveries and may trigger retries according to the configured retry policy.

Retry Behavior

Newline retries failed webhook deliveries using exponential backoff when it does not receive an HTTP 2xx response.

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.

Retry Testing

Test retries by temporarily making your receiving endpoint unavailable and generating a qualifying event:

1. Disable the receiving webhook endpoint.
2. Generate a qualifying webhook event.
3. Allow retry attempts to occur.
4. Re-enable the endpoint before the final retry attempt.
5. Verify receipt of the final retry event.

Optional: Health Checks

Newline supports health checks against a /health endpoint when one is available. You do not need to implement this endpoint to receive webhook deliveries.

If you implement a health endpoint, use it for:

• Connectivity validation.
• Operational monitoring.
• Environment readiness checks.

Common Delivery Failures

The following conditions may cause webhook delivery failures:

• Invalid webhook URL.
• DNS resolution failures.
• Endpoint timeouts.
• Network or firewall restrictions.
• Failed HMAC validation.
• Endpoint responses outside the HTTP 2xx range.

Monitor webhook delivery outcomes and investigate repeated failures.

Security Best Practices

• Validate webhook signatures before processing payloads.
• Verify the timestamp associated with incoming requests.
• Use HTTPS for every webhook endpoint.
• Store HMAC keys and private encryption keys where access is restricted.
• Reject requests that fail signature validation.
• Process webhook requests asynchronously when possible.
• Return an HTTP 2xx response only after your endpoint has accepted the request for processing.

Prepare for duplicate webhook deliveries. Use the unique event identifier to make processing idempotent (so processing the same event more than once has the same result as processing it once).