Webhook Development

The lomi. CLI provides tools to help you manage webhook endpoints for your integration.

Registering Webhooks

Use the webhook register command to set up a new webhook endpoint:

lomi webhook register

The command will prompt you for:

• Your merchant ID
• The webhook URL
• Events to subscribe to

Example events include:

• payment.success
• payment.failed
• payment.pending
• refund.success
• refund.failed

Managing Webhooks

List your registered webhook endpoints:

lomi webhook list --merchant-id your_merchant_id

This shows:

• Webhook ID
• URL
• Subscribed events
• Active status
• Last triggered timestamp

Security

When a webhook is registered, you’ll receive a verification token. Store this securely - you’ll need it to verify webhook signatures.

Local Development

The CLI includes a development server for testing webhooks locally:

lomi dev --port 3000

This starts a server that:

• Listens for incoming webhook events
• Displays webhook headers and payload
• Shows verification tokens
• Logs all requests for debugging

The server will print detailed information about each received webhook, making it easy to debug your integration.

Development Setup

1. Create a webhook endpoint in your application that can receive POST requests

2. Register the webhook using the CLI:

lomi webhook register

3. Use the verification token to validate incoming webhooks:

import crypto from 'crypto';
 
function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return hmac === signature;
}

Best Practices

1. Always verify signatures

   • Use the verification token to validate webhook authenticity
   • Reject requests with invalid signatures

2. Handle retries

   • Implement idempotency using the event ID
   • Return 2xx status for successful processing
   • Return 5xx status for retryable errors

3. Monitor webhook health

   • Track successful and failed deliveries
   • Set up alerts for repeated failures

Next Steps

• Configuration - Advanced webhook settings