Skip to main content

​
Webhook Setup

Learn how to configure webhook endpoints to receive real-time events.

​
Creating an Endpoint

1

Go to Dashboard

Navigate to app.ledger.so
2

Open Webhooks

Go to Settings > Webhooks
3

Add Endpoint

Click Add Endpoint and enter your URL
4

Select Events

Choose which events to subscribe to
5

Save

Copy your signing secret for verification

​
Endpoint Requirements

Your webhook endpoint must:
  • Use HTTPS (required in production)
  • Accept POST requests
  • Return 2xx status within 30 seconds
  • Accept application/json content type

​
Example Endpoint

const express = require('express');
const { Webhook } = require('svix');

const app = express();
app.use(express.raw({ type: 'application/json' }));

const webhook = new Webhook(process.env.WEBHOOK_SECRET);

app.post('/webhooks/ledger', (req, res) => {
  try {
    const payload = webhook.verify(req.body, {
      'svix-id': req.headers['svix-id'],
      'svix-timestamp': req.headers['svix-timestamp'],
      'svix-signature': req.headers['svix-signature']
    });

    switch (payload.type) {
      case 'transaction.completed':
        handleTransaction(payload.data);
        break;
      case 'card.created':
        handleCardCreated(payload.data);
        break;
      // ... handle other events
    }

    res.status(200).send('OK');
  } catch (err) {
    console.error('Webhook error:', err);
    res.status(400).send('Invalid signature');
  }
});

​
Managing Endpoints

​
Update Endpoint

  1. Go to Settings > Webhooks
  2. Click on the endpoint
  3. Update URL or subscribed events
  4. Save changes

​
Rotate Secret

If your signing secret is compromised:
  1. Go to Settings > Webhooks
  2. Click on the endpoint
  3. Click Rotate Secret
  4. Update your server with the new secret
After rotating, you have 24 hours to update your server. Both old and new secrets work during this period.

​
Delete Endpoint

  1. Go to Settings > Webhooks
  2. Click on the endpoint
  3. Click Delete
  4. Confirm deletion

​
Testing Webhooks

​
Send Test Event

  1. Go to Settings > Webhooks
  2. Click on the endpoint
  3. Click Send Test Event
  4. Select event type
  5. View delivery result

​
Local Development

Use a tunnel service for local testing: 
# Using ngrok
ngrok http 3000

# Use the ngrok URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/ledger

​
Monitoring

View webhook delivery status in the Dashboard:
  • Delivered - Successfully received
  • Pending - Awaiting delivery
  • Failed - All retries exhausted
Click on any event to see:
  • Request payload
  • Response status
  • Delivery attempts
  • Error messages