Overview

This guide outlines how to subscribe to Newline Webhooks topics, including setup, registration, authentication, and best practices. Webhooks allow clients to receive real-time event notifications via secure HTTPS endpoints.

Newline sends event messages to predefined topics. Clients can subscribe at:

Topic-level: Receive all events under a topic (e.g., all transfer events).
Event-level: Subscribe to specific event types (e.g., only RTP Settlement).
Combination: Mix topic and event-level subscriptions for granular control.

Topic Naming Convention

Webhook topics follow this format:

<client>.<environment>.<topic_name>

Example: neal.abc-enterprises.sandbox.transaction

Topic names are predefined by Newline and provided during onboarding.

Registration Process

To subscribe to Webhooks:

Contact Newline Onboarding Support (NOS) Provide:
- A secure Base URL (must be HTTPS)
- A public encryption key
- A list of topics you wish to subscribe to
📧 Email: [email protected] or submit via ServiceNow.
Receive Credentials Newline will issue:
- An HMAC key used to sign each webhook event
Confirm Test Event Processing Clients must confirm receipt and successful processing of a test event before production delivery is enabled.
Enable Subscription Once confirmed, Newline will activate the subscription in the production environment.

Subscription Behavior

Each event includes a unique event_id for idempotency.
Webhook endpoints must respond within 5 seconds.
Newline retries delivery up to 3 times.
If all retries fail, a health check may be sent to /webhooks/health.

Managing Subscriptions

To unsubscribe or update your Webhooks subscriptions:

Contact NOS and specify the topics or events to remove.
Subscriptions will be updated or terminated accordingly.

Best Practices

Validate HMAC signatures for every event.
Implement idempotency using event_id.
Ensure your endpoint is highly available and responds within SLA.
Monitor your /webhooks/health endpoint for diagnostics.
Test thoroughly in the sandbox environment before going live.