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. It must be a public http(s) address: private, loopback and cloud metadata addresses are refused, and redirects are not followed
  • Events — which events to send (e.g., issue.created, issue.updated)
  • Signing secret — generated automatically and shown once after creation. Save it securely; it cannot be retrieved later

Payload Format

{
  "id": "delivery_uuid",
  "event": "issue.updated",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "workspace": { "id": "workspace_uuid" },
  "data": {
    "issue": {
      "id": "issue_uuid",
      "identifier": "ENG-42",
      "title": "Fix login bug",
      "team_id": "team_uuid",
      "status_id": "status_uuid",
      "priority": 1,
      "assignee_id": "user_uuid",
      "project_id": null,
      "cycle_id": null,
      "due_date": null,
      "created_at": "2026-01-14T09:00:00.000Z",
      "updated_at": "2026-01-15T10:30:00.000Z"
    },
    "changes": {
      "status_id": { "from": "status_uuid_before", "to": "status_uuid" }
    },
    "actor_id": "user_uuid"
  }
}

priority is 0 (urgent) to 4 (none). changes appears on issue.updated and lists status, assignee and priority transitions. comment.created carries comment (id, body) alongside issue. Each delivery also sends the event name in X-Velocity-Event and the delivery ID in X-Velocity-Delivery.

issue.status_changed

Configured status sync from GitHub, Sentry, PagerDuty, Bitbucket, Opsgenie and Datadog also sends these events. Automatic changes use actor_id: null and appear as System in issue activity. Automation status actions send notifications and webhooks without triggering another automation. A callback that leaves the status unchanged does not send another transition.

Sent alongside issue.updated whenever an issue moves to another status, with both statuses spelled out. A status's type is its group: backlog, unstarted, started, completed or cancelled.

"data": {
  "issue": { "id": "issue_uuid", "identifier": "ENG-42", "status_id": "status_done", … },
  "change": { "from": "status_progress", "to": "status_done" },
  "from_status": { "id": "status_progress", "name": "In Progress", "type": "started" },
  "to_status": { "id": "status_done", "name": "Done", "type": "completed" },
  "actor_id": "user_uuid"
}

project.created and project.updated

project.updated is sent on every save of a project, and updated_fields lists the fields that save set (not necessarily changed).

"data": {
  "project": {
    "id": "project_uuid",
    "name": "Website Redesign",
    "identifier": "WR",
    "description": null,
    "status": "in_progress",
    "lead_id": "user_uuid",
    "start_date": "2026-09-01",
    "target_date": "2026-12-01",
    "created_at": "2026-08-20T09:00:00.000Z",
    "updated_at": "2026-09-26T12:00:00.000Z"
  },
  "updated_fields": ["status"],
  "actor_id": "user_uuid"
}

project.created has the same shape without updated_fields.

cycle.started and cycle.completed

Sent when Velocity moves a cycle to active or completed by its dates. That happens hourly, so these arrive within an hour of midnight UTC on the cycle's start or end date (see Cycles). There is no actor_id.

"data": {
  "cycle": {
    "id": "cycle_uuid",
    "name": "Sprint 14",
    "team_id": "team_uuid",
    "status": "active",
    "start_date": "2026-09-22",
    "end_date": "2026-10-06",
    "created_at": "2026-09-01T09:00:00.000Z",
    "updated_at": "2026-09-22T00:05:00.000Z"
  }
}

Signature Verification

Each delivery includes an X-Velocity-Signature header containing an HMAC-SHA256 signature of the raw request body, prefixed with sha256=.

New and rotated webhooks sign directly with the secret shown in Settings. Verify the raw body bytes before parsing JSON: re-serializing an object can change the bytes. The secret is encrypted at rest and never returned by ordinary reads.

const crypto = require('crypto');

function verifySignature(rawBody, signature, secret) {
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');

  const a = Buffer.from(signature || '');
  const b = Buffer.from(expected);

  // timingSafeEqual throws a RangeError when the buffers differ in
  // length — which is the common case for a wrong signature. Compare
  // lengths first so a mismatch returns false instead of crashing.
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

Legacy webhooks

Webhooks created before the outbound-secret update retain their original signature format until rotated. Settings labels these as legacy; GraphQL exposessigningKeyMode: SHA256. For these only, derive the HMAC key withcrypto.createHash('sha256').update(secret).digest('hex'). Backfilling their encrypted storage does not change their signatures.

Rotating a signing secret

A workspace owner or admin can open a webhook and choose Rotate secret. The new secret is shown once; closing the dialog clears it. New deliveries and retries immediately use the new raw secret (signingKeyMode: RAW), so update the receiver before sending more events. In-flight deliveries may still carry the old signature. Rotation has no overlap window and never reveals the previous secret. Zapier and Make subscriptions do not use this rotation flow.

The create and rotate GraphQL mutations return signingSecret only in that mutation response. Ordinary webhook reads return no secret. If signing-key encryption is unavailable, creation and rotation fail; Settings deliveries with an unavailable key are blocked instead of being sent unsigned.

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.

Deduplicate attempts using X-Velocity-Delivery, which matches the envelope's id and stays the same on manual and scheduled retries. New deliveries, including Send test, use this ID for their history row too. Older history rows can have a different internal row ID: use that row ID withretryWebhookDelivery, while the receiver continues to receive the original envelope ID. Existing payloads and row IDs are not rewritten. A legacy envelope without a valid header-safe ID uses its history row ID as the fallback.

Verify the signature against each attempt's raw body bytes before deduplicating. JSON stored in history can be re-serialized for a retry, and retries use the current signing key after rotation.

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.

Unsubscribing with 410 Gone

A 410 Gone response is final: the delivery is not retried and doesn't count as a failure. A webhook created in Settings → Webhooks is turned off, and you can turn it back on there. A hook that Zapier, Make or another tool subscribed through the automation API is deleted. Zapier answers 410 once a Zap is turned off or deleted, so its hook goes away with it.

Hooks from Zapier and Make

Hooks subscribed by Zapier or through the automation API appear in this list too. Each belongs to the person who subscribed it and is removed when that person leaves the workspace. These hooks have no signing secret, so their deliveries carry an empty X-Velocity-Signature.

Available Events

EventDescription
issue.createdA new issue was created
issue.updatedAn issue was modified, including status and assignee changes
issue.status_changedAn issue moved to another status (also sent as issue.updated)
issue.deletedAn issue was deleted
comment.createdA comment was added
project.createdA project was created
project.updatedA project was saved
cycle.startedA cycle became active on its start date
cycle.completedA cycle was completed on its end date