Guides
Learn More about Newline

Webhook Subscriptions

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 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:

{base_url}/{topic}

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

Topic names are predefined by Newline and provided during onboarding.

Registration Process

To subscribe to Webhooks:

  1. Contact Newline Onboarding Support (NOS). Provide:

    • A Base URL (must be HTTPS)
    • A public encryption key
    • A list of topics you wish to subscribe to

    Contact Newline support at [email protected] or submit the request via ServiceNow.

  2. Receive Credentials. Newline will issue:

    • An HMAC key used to sign each webhook event

  3. Confirm Test Event Processing. Clients must confirm receipt and successful processing of a test event before production delivery is enabled.

  4. 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.

Related Pages