What is a Webhook?

A webhook event is a real-time notification sent from Newline to your system when specific actions occur (e.g., a deposit is received or a payment is initiated). Webhooks are an alternative to polling a message queue and are recommended for most clients.

Message Queue vs. Webhooks

• Webhooks: Push-based. Newline sends events to your API endpoint.
• Message Queue (MQ): Pull-based. You retrieve events from a queue.
• Recommendation: We encourage using webhooks for simplicity and real-time responsiveness. However, you may choose MQ if it better fits your architecture.

Getting Started with Webhooks

Prerequisites

Before registering for webhook events, ensure the following:

1. Secure API Endpoint: Set up an HTTPS endpoint to receive webhook events. Use a consistent naming convention such as /webhooks/transfers.
2. HMAC Key: Newline will provide an HMAC secret used to sign webhook payloads. You must validate this signature to ensure authenticity.
3. Idempotency Handling: Each event includes a unique ID in the header. Your system should track these IDs to prevent duplicate processing.
4. Sandbox Testing: Test your webhook implementation in the sandbox environment before going live.

Registration Process

To register for webhook events:

1. Provide the following to the Newline Onboarding Support (NOS) team:
   • Public encryption key
   • Base URL for webhook delivery
   • List of topics (event types) you want to subscribe to
2. NOS will configure your webhook subscription.
3. QA will validate the integration flow.

Webhook Delivery and Retry Logic

• Your endpoint must respond within 5 seconds.
• If no response is received, Newline will retry up to 3 times.
• If delivery fails consistently, we may call a health check endpoint (recommended path: /webhooks/health).

Managing Subscriptions

To update or cancel your webhook subscriptions, contact the NOS team with the relevant topics or events.

Best Practices

• Validate HMAC signatures on all incoming events.
• Use idempotency keys to avoid duplicate processing.
• Log all received events for traceability.
• Monitor your health endpoint to ensure availability.