Webhook Setup Guide

Webhooks allow the Leypal platform to push real-time notifications to your server the moment something happens — a signer completes a document, an identity verification finishes, or a signature is cancelled. Instead of polling the API every few seconds to detect changes, your endpoint receives a single HTTP POST request the instant the event occurs.

Why webhooks matter:

• Real-time: Your system reacts immediately — no polling loops, no stale data
• Reliable: Leypal retries failed deliveries automatically, so transient outages don't cause missed events
• Automatic: All available events are delivered to your endpoint automatically — no filtering required

Common scenarios where webhooks are essential: updating a database record when a signature is completed, sending a confirmation email to a client, or triggering a downstream workflow when identity verification passes.

Prerequisites

Before registering a webhook, make sure you have:

• An active Leypal API key (see Authentication)
• A publicly accessible HTTPS endpoint — localhost URLs will not work; Leypal must be able to reach your server from the internet
• The ability to handle HTTP POST requests and return a response code within 30 seconds

HTTPS required: Leypal only delivers webhooks to https:// URLs. Plain http:// endpoints will be rejected at registration. For local development, use a tunneling tool such as ngrok or Cloudflare Tunnel.

Step-by-Step Registration

Step 1: Open the Api & Webhooks Section

1. Log in to the Leypal Dashboard
2. Navigate to Api & Webhooks (main menu)
3. Click the Webhooks tab
4. Click Add Webhook Endpoint

All webhooks are registered in the Api & Webhooks section.

Step 2: Enter Your Webhook URL

In the Endpoint URL field, enter the public URL of your server that will receive webhook events:

https://yourdomain.com/webhooks/leypal

URL requirements:

• Must start with https://
• Must be reachable from the public internet
• The path is your choice — use any route that makes sense in your application

For local testing: Expose your local server with ngrok:

ngrok http 3000
# Leypal will deliver to: https://abc123.ngrok.io/webhooks/leypal

Step 3: All Events Are Enabled by Default

Your webhook endpoint automatically receives all available events. There is no event filtering — every signature and identity verification event will be delivered to your endpoint.

Signature events you will receive:

Identity verification events you will receive:

How to handle this: Build your webhook handler to filter events based on event.type in your application code. Ignore event types you don't need to process.

Step 4: Save the Endpoint

Click Save Endpoint to register the webhook. The endpoint will be active and ready to receive events immediately.

HTTP Response Codes

Your endpoint must respond to each webhook delivery. Leypal uses your HTTP response code to determine whether the delivery was successful.

What Leypal Expects

Respond as quickly as possible — ideally within 1-2 seconds. If your business logic takes longer, queue the event and process it asynchronously. Return the HTTP status code immediately after receipt.

Response Code Behavior

Best practice: Return 200 OK immediately after receiving and queuing the event. Do not wait for your business logic to complete before responding. If your processing logic throws an exception, Leypal will retry the delivery even though you already processed it — build your handler to be idempotent (safe to run twice with the same event).

Idempotency

Each webhook delivery includes a unique ID in the payload (webhookId). Store processed webhook IDs in your database and check before processing:

// Pseudo-code: idempotency check
const webhookId = payload.webhookId;

const alreadyProcessed = await db.webhookEvents.findOne({ webhookId });
if (alreadyProcessed) {
  // Return 200 immediately — duplicate delivery
  return res.status(200).end();
}

await db.webhookEvents.insert({ webhookId });
await processEvent(payload);

return res.status(200).end();

Retry Policy

Leypal automatically retries failed deliveries to protect against transient outages on your server.

Key details:

• Maximum 5 attempts per webhook event — including the initial delivery
• Exponential backoff with a ~5 minute base delay between retry attempts
• After 5 failed attempts, the delivery is permanently marked as failed — no further retries
• Failed events are visible in the Webhook History section of the Dashboard for the affected endpoint
• You can manually replay a failed event from the Dashboard for debugging purposes

Monitoring tip: Set up alerting on your server for repeated 5xx responses on your webhook route. A sudden spike of errors on that route often means a code deployment broke your handler.

Viewing Webhook History

The Leypal Dashboard shows a log of every delivery attempt for each registered endpoint:

1. Go to Api & Webhooks → Webhooks
2. Find your endpoint in the list
3. Click View Logs to see all delivery attempts

Each log entry shows:

• Event Type — the type of event delivered (e.g., signature.completed)
• Timestamp — when the event was delivered
• Request Payload — the complete JSON payload Leypal sent
• Response Status Code — the HTTP status code your endpoint returned (e.g., 200 OK, 500 Internal Server Error)
• Response Body — the response body your endpoint returned
• Retry Status — whether Leypal will retry this delivery (based on your response code)

Use the history view to debug failed deliveries, verify that your endpoint is receiving the right events, and replay events during development.

Next Steps

Your webhook is now registered. Here's what to do next:

• Webhook Event Reference — Full payload schemas for every event type, with example JSON for each
• Troubleshoot Webhook Delivery — Common delivery failures and how to diagnose them