Overview

Newline’s Webhooks system provides a push-based mechanism for delivering real-time event notifications. It is designed for clients who want immediate updates with minimal infrastructure setup and prefer HTTPS-based delivery over queue-based consumption.

What Are Webhooks?

Webhooks allow Newline to send event notifications directly to your HTTPS endpoint as soon as an event occurs. This push-based model is ideal for clients who need real-time responsiveness and prefer a simpler integration path compared to message queues.

Webhooks are secured using HMAC signatures to ensure payload integrity and authenticity.

Key Features

Push Delivery: Events are sent directly to your endpoint.
Simple Setup: Requires only a secure HTTPS endpoint and public encryption key.
Automatic Retry Logic: Failed deliveries are retried up to 10 times with exponential backoff.
Event-Level Control: Subscribe to specific events or entire topics.

Getting Started

To begin using Webhooks, follow these steps:

Review authentication requirements. Learn how to validate Webhook signatures and secure your endpoint in Webhooks Authentication.
Understand available topics. Explore the list of supported topics and their naming conventions in Webhooks Topics.
Review topic definitions. Get detailed descriptions of each topic and the events they include in Webhooks Topic Definitions.
Set up subscriptions. Follow the steps to register your endpoint and manage subscriptions in Webhooks Subscriptions.

Best Practices

Validate HMAC signatures for every event.
Ensure your endpoint can safely handle duplicate deliveries.
Ensure your endpoint responds within 5 seconds. (Otherwise we will retry the event up to 10 times with exponential backoff before marking it as failed.)
In case of failure, we will monitor your <webhook_base_url>/<topic_name>/health endpoint for delivery diagnostics, where <webhook_base_url> is your registered webhook base URL and <topic_name> is the subscribed topic name.
Test thoroughly in sandbox before going live.