Understanding Webhooks

Webhooks are the backbone of real-time integrations at #divisions. They allow our platform to instantly notify your systems when specific events occur, eliminating the need for inefficient polling and ensuring your workflows stay synchronized.

What Are Webhooks?

Unlike traditional APIs where your application must repeatedly ask "has anything changed?", webhooks work in reverse. When an event triggers in #divisions, we automatically send an HTTP POST request to a URL you specify. This "push" model ensures you receive data the moment it's ready, reducing latency and server load.

How It Works at #divisions

1. Event Trigger: A user action, system state change, or scheduled job occurs in your #divisions workspace.
2. Payload Generation: We package the event data into a JSON payload with metadata.
3. Delivery: An HTTP POST request is sent to your registered endpoint URL.
4. Response: Your server must respond with a 2xx status code within 5 seconds to acknowledge receipt.

Payload Structure

Every webhook payload follows a consistent schema. Here's a standard example for a deployment.success event:

{
  "id": "evt_8x92k1m0p3",
  "type": "deployment.success",
  "timestamp": "2025-11-12T14:32:00Z",
  "workspace_id": "ws_7f829a",
  "data": {
    "project_id": "proj_4b21",
    "environment": "production",
    "version": "v2.4.1",
    "deployed_by": { "id": "usr_9921", "name": "Alex Chen" }
  }
}

Security & Verification

At #divisions, we sign every webhook request using HMAC-SHA256 to ensure payload integrity and origin authentication. Always verify signatures before processing events.

const crypto = require('crypto');

async function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const expected = hmac.digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Include your webhook secret in the X-Divisions-Signature header when sending test payloads locally.

Production Best Practices

• Handle retries gracefully: #divisions retries failed deliveries up to 5 times with exponential backoff. Design your endpoint to be idempotent.
• Acknowledge quickly: Respond with 200 OK immediately. Process heavy tasks asynchronously in the background.
• Use HTTPS: We only deliver webhooks to secure endpoints. Self-signed certificates will be rejected.
• Log & monitor: Track delivery status, latency, and error rates. Set up alerts for consecutive failures.
• Rotate secrets: Regenerate webhook signing keys periodically and maintain backward compatibility during transitions.

Common Issues & Fixes

Timeout Errors (5s limit)

Ensure your endpoint doesn't block on database writes or external API calls during the initial response phase. Queue the payload for background processing instead.

Signature Mismatch

Verify you're using the correct signing secret and that the raw body payload matches exactly what's sent. Encoding differences (UTF-8 vs ASCII) can cause hash mismatches.

4xx/5xx Response Codes

Check your server logs for routing errors, middleware blocks, or TLS configuration issues. Use our Webhook Debugger to simulate deliveries.

Next Steps

Ready to integrate? Head to your workspace settings, navigate to Integrations → Webhooks, and register your first endpoint. Our CLI and SDKs include built-in local tunneling for seamless development testing.