Webhooks

Overview

Every webhook delivery is an HTTP POST to your endpoint with a JSON body, four signature headers, and a 10-second timeout. Deliveries are retried up to five times with exponential backoff on failure.

Plan Availability

Registering an Endpoint

Open Project → Settings → Webhooks and click Add endpoint. Fill in:

Payload Envelope

Every delivery POSTs a JSON body with this shape:

{
  "id": "evt_01HY...",
  "event": "feedback.created",
  "timestamp": "2026-03-25T10:00:00Z",
  "workspace_id": "01HY...",
  "project_id": "01HY...",
  "data": { }
}

Event Catalog

Example Payloads

feedback.created

{
  "id": "evt_01HY...",
  "event": "feedback.created",
  "timestamp": "2026-03-25T10:00:00Z",
  "workspace_id": "01HY...",
  "project_id": "01HY...",
  "data": {
    "id": "01HY...",
    "type": "bug",
    "title": "App crashes on login screen",
    "description": "When I tap the login button...",
    "status": "open",
    "priority": "medium",
    "created_at": "2026-03-25T10:00:00Z"
  }
}

feedback.status_changed

{
  "data": {
    "id": "01HY...",
    "old_status": "open",
    "new_status": "in_progress",
    "changed_by": "tm_01HY..."
  }
}

Signature Verification

Every delivery includes four headers for verification:

X-Swake-Signature:   sha256=a1b2c3d4e5f6...
X-Swake-Timestamp:   1711353600
X-Swake-Event:       feedback.created
X-Swake-Delivery-Id: evt_01HY...

The signature is computed as HMAC-SHA256(secret, "{timestamp}.{rawBody}"). The payload is the Unix timestamp joined with the raw request body by a . separator.

const crypto = require('crypto');

function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-swake-timestamp'];
  const receivedSig = headers['x-swake-signature'].replace('sha256=', '');

  // Reject stale deliveries (> 5 minutes)
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    throw new Error('Delivery timestamp too old');
  }

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(receivedSig), Buffer.from(expected))) {
    throw new Error('Invalid signature');
  }
}

Delivery Semantics

Swake considers any 2xx response a success. Non-2xx responses and network errors trigger the retry schedule below. Each attempt has a 10-second timeout.

Testing Webhooks

Click Test on any endpoint in the portal to send a test.ping delivery. The portal shows the HTTP status and response time of the test request.

{
  "id": "evt_test_01HY...",
  "event": "test.ping",
  "timestamp": "2026-03-25T10:00:00Z",
  "workspace_id": "01HY...",
  "project_id": "01HY...",
  "data": { "message": "Webhook is working!" }
}

SSRF Prevention

To protect against Server-Side Request Forgery, the following endpoint URLs are always rejected:

Delivery Log

Open Settings → Webhooks → {endpoint} → Deliveries to see a paginated log of all delivery attempts, including:

Rotating the Signing Secret

If your secret is compromised:

API Reference

All endpoints are under /v1/portal/projects/:projectId/webhooks and require a valid JWT session cookie.