Developer API
Developer APIWebhooksTesting

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
  1. Call POST /v1/webhooks/{webhookId}/test for your subscription
  2. Check your logs or server to verify receipt of the delivery
  3. Confirm your signature verification succeeded

Local Development with ngrok

To test webhooks during local development, expose your local server to the internet using ngrok:

  1. Install ngrok from ngrok.com/download
  2. Authenticate with your ngrok token: ngrok config add-authtoken YOUR_TOKEN
  3. Start your local webhook server (e.g., npm run dev on port 3000)
  4. In another terminal, run: ngrok http 3000
  5. Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
  6. Create or update your webhook subscription with that URL
  7. Call POST /v1/webhooks/{webhookId}/test to 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:

  1. Go to webhook.site
  2. Copy your unique URL (e.g., https://webhook.site/abc123...)
  3. Create a webhook subscription with that URL
  4. Call POST /v1/webhooks/{webhookId}/test to see the delivery arrive in real time
  5. 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:4040 while ngrok is running to see all requests to your tunnel.

See Also