Webhook Authentication

Overview

To receive event notifications via Webhooks, authenticate each incoming message to verify its integrity and origin. Authentication is handled using HMAC signatures, and webhook deliveries use secure HTTPS endpoints.

Prerequisites

After selecting your subscription topics or events, Newline will issue:

• HMAC Key: Used to sign each Webhook event.

You will provide Newline with:

• Encryption Key: Used to encrypt all messages, adding another layer of security.
• Topic Names: Provided during onboarding and used to identify the source of each event.
• Base URL: The HTTPS endpoint where events will be delivered. Newline appends the topic name as the final path segment (e.g., with base URL https://example.com/webhooks, transfer topic events would be sent to https://example.com/webhooks/transfers).

Secure Delivery Requirements

Webhook connections are expected to:

• Use HTTPS for endpoint security
• Validate the HMAC signature included in the X-Request-Signature-SHA-256 header
• Include a timestamp in the X-Request-Signature-Timestamp header for signature validation
• Respond within 5 seconds to avoid delivery failure and retries

Signature Validation

To verify the authenticity of each Webhook event:

1. Concatenate the raw request body and the X-Request-Signature-Timestamp header value
2. Compute the HMAC using the provided key and the SHA-256 algorithm
3. Compare the result to the value in the X-Request-Signature-SHA-256 header

Example validation logic:

payload = request_body + timestamp_header
signature = HMAC_SHA256(payload, hmac_key)

Reject Webhook requests with invalid signatures and log these events for security auditing.

Endpoint Requirements

Webhook events are delivered to the client-provided base URL, with the topic name appended as the final path segment:

{base_url}/{topic}

Examples

https://example.com/webhooks/transfers
https://example.com/webhooks/virtual_reference_number

How It Works

• The base URL is registered by the client
• Newline appends the topic name as the final path segment
• Clients support handling requests at dynamic topic-based paths

Requirements

• Keep the endpoint publicly accessible
• Support dynamic topic-based paths instead of hardcoding a single static endpoint path

API Key in Webhook URLs

Clients may include an API key in their webhook endpoint URL for additional security.

Supported Format

Include the API key as part of the base URL, before the topic path:

{base_url_with_api_key}/{topic}

Example

https://example.com/webhooks/{api_key}/transfers
https://example.com/webhooks/{api_key}/virtual_reference_number

Not Supported

Appending the API key after the topic path is not supported:

{base_url}/{topic}/{api_key} 

Example:

https://example.com/webhooks/transfers/{api_key} 

Additional Considerations

• The API key is treated as part of the base URL string
• If the API key changes, update the registered base URL
• Frequent API key rotation may increase operational overhead

Tips for Implementation

• Store and protect your HMAC key securely
• Implement idempotency using the event ID included in each payload
• Ensure your endpoint supports dynamic routing based on topic paths (e.g., /transfers, /virtual_reference_number)
• Monitor your endpoint health for diagnostics
• Test thoroughly in the sandbox environment before going live