Webhooks

What are Webhooks?

Webhooks are HTTP callbacks that notify your application when specific events occur in Corridorly. Instead of continuously polling our API for updates, we push event data to your specified endpoint in real-time.

Delivery Tiers

Choose between Standard and Premium tiers based on your SLA requirements. Premium offers faster retries and dedicated infrastructure.

Getting Started

// Express.js example
app.post('/webhooks/corridorly',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-corridorly-signature'] as string;
    const timestamp = req.headers['x-corridorly-timestamp'] as string;
    const payload = req.body.toString('utf8');

    // Verify signature
    if (!verifySignature(payload, signature, timestamp)) {
      return res.status(401).send('Invalid signature');
    }

    // Process asynchronously
    processEventAsync(JSON.parse(payload)).catch(console.error);

    // Acknowledge immediately
    res.status(200).send('OK');
  }
);

URL Requirements

Webhook URLs must meet strict security requirements to prevent SSRF attacks.

Event Types

Subscribe to all events or filter to specific types.

{
  "id": "evt_def456",
  "timestamp": "2025-11-08T12:05:00Z",
  "type": "Symphony Execution Completed",
  "tenantId": "tenant_xyz",
  "symphonyId": "symp_456",
  "data": {
    "executionId": "exec_789",
    "status": "success",
    "result": { "success": true }
  }
}

{
  "id": "evt_jkl012",
  "timestamp": "2025-11-08T12:10:00Z",
  "type": "Payment Event",
  "tenantId": "tenant_xyz",
  "data": {
    "paymentId": "pay_123",
    "amount": 1000,
    "currency": "USD",
    "status": "succeeded"
  }
}

{
  "id": "evt_pqr678",
  "timestamp": "2025-11-08T12:20:00Z",
  "type": "approval.decision.recorded",
  "tenantId": "tenant_xyz",
  "data": {
    "approvalId": "apr_123",
    "decision": "approved",
    "decidedBy": "user_def"
  }
}

Security & Verification

Always verify webhook signatures to ensure authenticity.

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  // 1. Validate timestamp (within 5 minutes)
  const currentTime = Date.now();
  const requestTime = parseInt(timestamp, 10);
  if (Math.abs(currentTime - requestTime) > 300000) {
    return false;
  }

  // 2. Create signed payload
  const signedPayload = `${timestamp}.${payload}`;

  // 3. Generate expected signature
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(signedPayload);
  const expectedSignature = hmac.digest('hex');

  // 4. Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Retry Behavior

Failed deliveries are automatically retried with exponential backoff.

Best Practices

Troubleshooting

Testing Webhooks

# Install and start ngrok
npm install -g ngrok
ngrok http 3000

# Use the HTTPS URL as your webhook endpoint