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, and each event includes a unique identifier for idempotency and traceability.

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 3 times.
• Event-Level Control: Subscribe to specific events or entire topics.

Getting Started

To begin using Webhooks, follow these steps:

1. Review Authentication Requirements Learn how to validate Webhook signatures and secure your endpoint. For more information visit Webhooks Authentication

2. Understand Available Topics Explore the list of supported topics and their naming conventions. For more information visit Webhooks Topics

3. Review Topic Definitions Get detailed descriptions of each topic and the events they include. For more information visit Webhooks Topic Definitions

4. Set Up Subscriptions Follow the steps to register your endpoint and manage subscriptions. For more information visit Webhooks Subscriptions

Best Practices

• Validate HMAC signatures for every event.
• Implement idempotency using event IDs.
• Ensure your endpoint responds within 5 seconds. (Otherwise we will retry the event 3 times and then mark the event as failed.)
• In case of failure, we will monitor your /webhooks/{topic_name}/health endpoint for delivery diagnostics.
• Test thoroughly in sandbox before going live.