Best Practices

​

Return Quickly

app.post('/webhooks/lynkwell', async (req, res) => {
  // Validate signature first
  // ...

  // Acknowledge immediately
  res.status(200).json({ received: true });

  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});

​

Handle Duplicates

const processedEvents = new Set<string>();

async function handleWebhook(event: WebhookEvent) {
  if (processedEvents.has(event.id)) {
    console.log('Duplicate event, skipping:', event.id);
    return;
  }

  processedEvents.add(event.id);
  // Process event...
}

​

Use HTTPS

​

Monitor Deliveries

curl 'https://api.lynkwell.com/webhooks/v1/webhook-endpoints/we_abc123/deliveries?limit=10' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​

Rotate Secrets

1. Create a new webhook endpoint with the same URL and events
2. Update your endpoint to accept signatures from both secrets temporarily
3. Delete the old webhook endpoint
4. Update your endpoint to only accept the new secret

​

Troubleshooting

​

Webhook Not Received

1. Verify your endpoint is accessible from the internet
2. Check that your endpoint returns a 2xx status code
3. Review the delivery attempts via the API for error details
4. Ensure your endpoint responds within 30 seconds

​

Invalid Signature

1. Make sure you’re using the raw request body (not parsed JSON)
2. Verify you’re using the correct webhook secret
3. Check that the timestamp hasn’t expired (default tolerance: 5 minutes)
4. Ensure you’re comparing the full signature, not truncated

​

Missed Events

curl 'https://api.lynkwell.com/webhooks/v1/webhook-events?limit=50' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'