Testing Webhooks
Validate webhook endpoints and signature handling before going live
Test Deliveries
The easiest way to test your webhook integration is the test-delivery endpoint. It sends a sample event with a valid signature so you can validate your endpoint without waiting for a real event.
POST /v1/webhooks/{webhookId}/test HTTP/1.1
Host: api.taglogger.com
Authorization: Bearer tl_live_xxx- Call
POST /v1/webhooks/{webhookId}/testfor your subscription - Check your logs or server to verify receipt of the delivery
- Confirm your signature verification succeeded
Local Development with ngrok
To test webhooks during local development, expose your local server to the internet using ngrok:
- Install ngrok from ngrok.com/download
- Authenticate with your ngrok token:
ngrok config add-authtoken YOUR_TOKEN - Start your local webhook server (e.g.,
npm run devon port 3000) - In another terminal, run:
ngrok http 3000 - Copy the HTTPS URL (e.g.,
https://abc123.ngrok.io) - Create or update your webhook subscription with that URL
- Call
POST /v1/webhooks/{webhookId}/testto trigger a delivery to your local server
Your local server will be publicly accessible at the ngrok URL for as long as ngrok is running.
Webhook.site Alternative
For quick testing without a local server, use webhook.site:
- Go to webhook.site
- Copy your unique URL (e.g.,
https://webhook.site/abc123...) - Create a webhook subscription with that URL
- Call
POST /v1/webhooks/{webhookId}/testto see the delivery arrive in real time - Inspect the request headers and body to verify signature verification logic
webhook.site is great for quick validation but doesn't run code, so you can't test signature verification there. Use ngrok to test the full handler.
Signature Verification in Tests
When the test endpoint sends a delivery, it uses your webhook's signing secret to generate a valid signature. Your handler should verify the signature before processing:
const crypto = require('crypto');
// Handler that verifies the webhook signature
app.post('/webhook', (req, res) => {
// Header format: "X-TagLogger-Signature: sha256=<hex>"
const header = req.headers['x-taglogger-signature'] || '';
const provided = header.replace(/^sha256=/, '');
const secret = process.env.WEBHOOK_SECRET;
// IMPORTANT: Use the raw body, not parsed JSON
const body = req.rawBody;
const expected = crypto
.createHmac('sha256', secret)
.update(body, 'utf8')
.digest('hex');
// Constant-time comparison to prevent timing attacks
const valid =
provided.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(provided), Buffer.from(expected));
if (!valid) {
console.error('Signature mismatch!');
return res.status(401).json({ error: 'Unauthorized' });
}
// Signature verified—safe to process
const event = JSON.parse(body);
console.log('Received event:', event.event);
res.sendStatus(200);
});Checklist Before Going Live
- Your endpoint is served over HTTPS
- Your endpoint responds with a 2xx status (for example, 200 OK) within 10 seconds
- You verify the X-TagLogger-Signature header before processing
- You handle the event asynchronously (respond immediately, process in the background)
- You skip duplicate IDs (store processed event IDs in your database)
- You use occurredAt timestamps to order events (they may arrive out of order)
- You poll GET /v1/fleet/delta on an interval as your source of truth
- You've tested the handler with the test delivery
- Your logs are capturing webhook deliveries for debugging
Debugging Tips
- Check server logs: Look for errors when handling the webhook delivery.
- Verify HTTPS: Your endpoint must be HTTPS. HTTP endpoints will be rejected.
- Test signature verification: Copy a webhook body and signature header; manually verify it matches.
- Check response code: Ensure your handler responds with 2xx (e.g., 200 OK), not 3xx or 4xx.
- Log the raw body: If signature verification fails, log the raw body to compare against the signature.
- Use ngrok inspector: Visit
http://localhost:4040while ngrok is running to see all requests to your tunnel.