Webhooks

Webhooks let your system react to Projects events in real time. Register a URL, subscribe to event types, and Workestra POSTs you a signed JSON payload every time one of those events happens.

Creating a Webhook

1. Go to Settings → Integrations → Webhooks (or Project → Settings → Integrations → Webhooks for project-scoped hooks)
2. Click New Webhook
3. Fill in:

4. Save

Event Types

Payload

{
  "id": "evt_1234567890",
  "type": "task.status_changed",
  "created_at": "2026-04-23T12:34:56Z",
  "workspace_id": "ws_abc123",
  "data": {
    "task_id": "task_def456",
    "project_id": "proj_ghi789",
    "title": "Fix login timeout",
    "old_status": "in_progress",
    "new_status": "in_review",
    "changed_by": "user_jkl012"
  }
}

Signature Verification

Every request includes a signature header:

X-Workestra-Signature: sha256=<hex>

The signature is HMAC-SHA256 of the raw request body using your webhook secret.

Verification (Node.js)

const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Verification (Python)

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Reject any request where verification fails.

Retry Policy

If your endpoint responds with a non-2xx or times out, Workestra retries with exponential backoff:

After 6 failures, the delivery is marked permanently failed. The webhook stays active — future events still fire — but that specific delivery won't be retried.

Best Practices

• Respond fast — return 2xx within a few seconds, then process async
• Be idempotent — handle the same id twice gracefully (retries are possible)
• Verify signatures on every request
• Log unverified events with enough info to debug without exposing the secret

Delivery History

At Settings → Integrations → Webhooks → [your webhook] → Deliveries, you can see:

• Event ID and type
• Timestamp
• HTTP status code returned
• Response body (first 1 KB)
• Redelivery button

Click any failed delivery to inspect and optionally redeliver.

Next Steps

• REST API — pull instead of push
• Automations — the webhook action fires the same way
• General webhooks overview — cross-module webhook reference