Webhook Verification

When creating a webhook, you can subscribe to any combination of available events based on your specific needs. This allows you to customize your webhook to only receive notifications for the events that matter most to your application.

When you receive a webhook from our system, you must verify the signature to ensure the request is authentic and hasn't been tampered with.

HMAC Signature Verification

Headers You'll Receive

• X-LYNXO-SIGNATURE: The HMAC signature for verification
• Content-Type: application/json

How to Verify the Webhook

1. Extract the webhook event ID from the payload:

   {
     "id": "wh_event_12345",
     "event": "job.created",
     "created_at": 1234567890,
     "data": { ... },
     "data_id": 456
   }
   

2. Use your webhook secret (provided when you created the webhook) to generate an HMAC signature

3. Create the signature using the webhook_event_id as the message and your secret as the key

4. Compare your generated signature with the X-LYNX-SIGNATURE header

Verification Example (JavaScript)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  // Extract the webhook event ID from payload
  const webhookEventId = payload.id;
  
  // Generate HMAC signature using your secret
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(webhookEventId)
    .digest('hex');
  
  // Compare signatures
  if (signature === expectedSignature) {
    // Webhook is verified - process the data
    return true;
  } else {
    // Signature mismatch - reject the webhook
    return false;
  }
}

// Usage
const isValid = verifyWebhook(
  webhookPayload, 
  req.headers['x-lynx-signature'], 
  'your_webhook_secret_here'
);

if (isValid) {
  // Process webhook data
  console.log('Webhook verified successfully');
} else {
  // Reject webhook
  console.log('Webhook verification failed');
}

Security Best Practices

• Never share your webhook secret - keep it secure
• Always verify signatures before processing webhook data
• Use HTTPS for your webhook endpoint
• Store secrets securely in environment variables or secure key management systems
• Reject webhooks with invalid signatures immediately

This verification ensures that only legitimate webhooks from our system are processed by your application.