Overview

To receive event notifications via Webhooks, clients must authenticate each incoming message to ensure its integrity and origin. Authentication is handled using HMAC signatures, and all webhook deliveries must be made to 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: This is used to encrypt all the messages adding another level 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.

Secure Delivery Requirements

All Webhook connections must:

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:

Concatenate the raw request body and the X-Request-Signature-Timestamp header value.
Compute the HMAC using the provided key and the SHA-256 algorithm.
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)

Clients must reject any Webhook requests with invalid signatures and log these events for security auditing.

Endpoint Requirements

Webhook events are delivered to the client-provided base URL, which must be:

Secure (HTTPS)
Publicly accessible
Capable of responding within 5 seconds

Use consistent endpoint naming conventions such as /webhooks/transfers.

Tips for Implementation

Store and protect your HMAC key securely.
Implement idempotency using the event ID included in each payload.
Monitor your /webhooks/{topic_name}/health endpoint for diagnostics.
Test thoroughly in the sandbox environment before going live.