Documentation

Custom Webhooks

Webhooks as a Service
Guaranteed Delivery

Send custom HTTP payloads to any endpoint when events happen in your system. Laneful handles all the hard parts—retries, queueing, failure recovery, and delivery guarantees—so you don't have to.

Automatic Retries
Message Queueing
Signed Payloads
Zero infrastructure required

No queues, workers, or retry logic to build or maintain

Any HTTP endpoint

Send to your own servers, third-party APIs, or internal services

See how it works →

On this page

Webhooks as a Service
Managed Delivery

Overview

Custom Webhooks let you send structured HTTP payloads to any endpoint in response to events—without managing any of the underlying infrastructure yourself. Whether you're notifying an internal service, triggering a third-party workflow, or syncing data across systems, Laneful ensures your webhooks are delivered reliably.

What Laneful handles for you

  • • Durable message queueing so no event is ever lost
  • • Automatic retries with exponential backoff on failure
  • • HMAC signature signing for endpoint verification
  • • Configurable timeout and retry policies

The Challenges

Building reliable webhook delivery yourself sounds simple at first—just make an HTTP request. In practice, production-grade webhook infrastructure is surprisingly difficult to get right.

Transient failures and timeouts

Endpoints go down. Networks blip. Servers restart. A fire-and-forget HTTP request will silently fail whenever the target is unavailable, with no way to recover the lost event.

Retry logic is harder than it looks

Naive retries can overwhelm a recovering endpoint or cause duplicate processing. Proper exponential backoff, jitter, and idempotency handling require significant engineering effort.

Queueing and backpressure

During traffic spikes, in-process queues fill up and events are dropped. Durable queueing requires external infrastructure—message brokers, workers, and careful configuration—just to ensure events survive a process crash.

Observability and debugging

When a webhook isn't received, you need visibility into what was sent, what response came back, and what happened during each retry attempt. Without built-in logging, root cause analysis is a blind hunt.

Security and authenticity

Without payload signing, any party can POST to your webhook endpoint and inject fake events. Implementing and rotating HMAC secrets correctly is easy to get wrong.

Laneful covers everything

Every one of these problems is handled for you. You define the endpoint and the payload shape—Laneful ensures it gets there, even if it takes multiple attempts across hours.

How It Works

Webhook Apps and Endpoints

A Webhook App is a container that groups one or more webhook endpoints together. It typically represents a single customer or destination system that needs to receive webhook events—for example, one Webhook App per customer account in your platform.

Inside each Webhook App you configure webhook endpoints—the individual delivery targets. Each endpoint has:

  • • URL — the HTTPS address that will receive the HTTP POST for each event
  • • Signing secret — a per-endpoint HMAC secret used to sign every payload so the receiver can verify authenticity
  • • Batch mode — optionally group multiple events into a single request to reduce HTTP overhead for high-volume streams

The delivery pipeline

1

Event is triggered

Your application fires an event via the Laneful API or dashboard. The event payload is durably persisted before any delivery is attempted.

2

Payload is signed and dispatched

Laneful signs the payload with your HMAC secret and sends an HTTP POST to your configured endpoint with the appropriate headers.

3

Response is evaluated

A 2xx response marks the delivery as successful. Any other status code, connection error, or timeout triggers the retry policy.

Example payload

Laneful sends a POST request to your endpoint with a JSON body shaped by your configuration:

POST https://your-service.example.com/hooks/laneful
Content-Type: application/json
X-Webhook-Signature: sha256=...

{
  "event": "order.completed",
  "timestamp": 1753502407,
  "data": {
    "order_id": "ord_8f2a1c",
    "customer_id": "cus_4b9d3e",
    "total": 9900,
    "currency": "usd"
  },
  "metadata": {
    "environment": "production",
    "source": "checkout-service"
  }
}

Retries & Queueing

When your endpoint is unavailable or returns an error, Laneful automatically retries delivery using exponential backoff with jitter. Events are held in a durable queue so they survive process restarts and traffic spikes without any work on your end.

Retry schedule

• Immediately after failure
• 1 minute later
• 5 minutes later
• 30 minutes later
• 2 hours later
• 6 hours later
• 24 hours later

After 24 hours the delivery is marked as permanently failed and no further retries are attempted.

Durable queueing

Every event is written to a durable store before dispatch. If your endpoint is down for hours, queued events continue retrying and are delivered as soon as your endpoint recovers—with no events dropped.

Best practice: respond quickly, process asynchronously

Return a 200 status as soon as you receive the request and handle the payload in a background job. This prevents timeouts from triggering unnecessary retries and keeps your endpoint resilient under load.

Security

Verifying webhook signatures

Every delivery is signed with your webhook secret using HMAC-SHA256. Verify the signature on your endpoint to confirm the request originated from Laneful:

const crypto = require('crypto');

function verifySignature(signature, payload, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  const received = signature.replace('sha256=', '');

  return crypto.timingSafeEqual(
    Buffer.from(received, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

// In your endpoint handler
app.post('/hooks/laneful', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const rawBody = JSON.stringify(req.body);

  if (!verifySignature(signature, rawBody, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Unauthorized');
  }

  // Safe to process
  res.status(200).send('OK');
});

Security checklist

  • • Always verify the HMAC signature before processing
  • • Use HTTPS endpoints only
  • • Store webhook secrets in environment variables, not source code
  • • Implement idempotency using the event ID to handle rare duplicates
  • • Apply rate limiting on your webhook endpoint as a safeguard

Getting Started

Set up your first custom webhook

1. Create a new webhook app

Workspace → Extra Services → Webhooks → Webhook Apps → Create Webhook App

2. Configure your endpoint

  • • Enter the HTTPS URL that will receive events
  • • Choose which event types should trigger this webhook
  • • Optionally define a custom payload template

3. Copy your signing secret

After saving, copy the generated HMAC secret and add it to your endpoint as an environment variable. You'll use it to verify incoming requests.

4. Send a test event

Use the "Send Test" button in the dashboard to fire a sample payload to your endpoint. Check the delivery log to confirm it was received and verify the response.

Ingest Events API

POST/v1/webhook/events

Submit one or more events for processing. The API accepts the request, durably queues the events, and returns immediately with an accepted status. Maximum 1000 events per request.

Sample Organization Endpoint

Below is a sample endpoint. After you register and create an organization, you'll get your unique endpoint:

https://custom-endpoint.api.laneful.com/v1/webhook/events

Replace custom-endpoint with your actual organization API endpoint.

Authentication

Pass your API key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request body

FieldTypeRequiredDescription
eventsarrayYesList of events to process. Cannot be empty. Maximum 1000 events.
events[].customer_idstringYesWebhook App ID.
events[].typestringYesEvent type, e.g. clicked, bounced, unsubscribed.
events[].payloadobjectYesArbitrary key-value data describing the event.

Example: single event

curl -X POST https://custom-endpoint.api.laneful.com/v1/webhook/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "customer_id": "1234",
        "type": "clicked",
        "payload": {
          "email": "alice@example.com"
        }
      }
    ]
  }'

Example: batch of events

curl -X POST https://custom-endpoint.api.laneful.com/v1/webhook/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "customer_id": "1234",
        "type": "clicked",
        "payload": { "email": "alice@example.com" }
      },
      {
        "customer_id": "1234",
        "type": "bounced",
        "payload": { "email": "bob@example.com", "reason": "mailbox full" }
      },
      {
        "customer_id": "1234",
        "type": "unsubscribed",
        "payload": { "email": "carol@example.com" }
      }
    ]
  }'

Responses

200

Events accepted

{ "status": "accepted" }
400

Validation error

{ "error": "No events to process" }
401

Unauthorized

Invalid or missing API key.