Webhooks

Send events to external services when things happen in Velocity.

Overview

Outgoing webhooks send HTTP POST requests to a URL you specify whenever events occur in your workspace. Use webhooks to build custom integrations, trigger CI/CD pipelines, update external dashboards, or sync data with other tools.

Creating a Webhook

Go to Settings → Webhooks and click New Webhook. Provide:

• URL — the endpoint that will receive POST requests
• Events — which events to send (e.g., issue.created, issue.updated)
• Secret — used to sign payloads (auto-generated if not provided)

Payload Format

{
  "event": "issue.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "workspace": {
    "id": "ws_123",
    "slug": "acme"
  },
  "data": {
    "id": "issue_456",
    "identifier": "ENG-42",
    "title": "Fix login bug",
    "status": "TODO",
    "priority": 2
  }
}

Signature Verification

Each delivery includes an X-Velocity-Signature header containing an HMAC-SHA256 signature of the request body. Verify it on your server:

const crypto = require('crypto');

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

Delivery History

The webhooks page shows a delivery history for each webhook with status codes, response times, and request/response bodies. Failed deliveries can be retried manually.

Auto-Disable

Webhooks that fail 10 consecutive deliveries are automatically disabled to prevent repeated failures. Re-enable them from the settings page after fixing the endpoint.

Available Events