Webhook Endpoints

Configure and manage real-time event subscriptions to receive automatic notifications about resource changes.

Creating a Webhook

Webhooks allow you to receive instant updates about events in Project Docs through HTTP callbacks. When creating a webhook, you must provide a unique URL where the event data will be sent.


curl -X POST https://api.example.com/webhooks \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "url": "https://your-service.com/webhook-endpoint",
  "events": ["project.created", "task.updated"]
}'

! Your endpoint must respond with HTTP 200 OK to all events. Failed deliveries will be retried with exponential backoff.

Webhook payloads include an HMAC signature header (X-Hub-Signature-256) for verification.

Sample Webhook Payload

Event: `task.updated`


{
  "event": "task.updated",
  "resource_id": "TASK-1234-ABCD",
  "timestamp": "2025-09-30T14:23:54Z",
  "data": {
    "id": "TASK-1234-ABCD",
    "name": "Design assets",
    "status": "completed",
    "updated_by": {
      "id": "USER-7890-ZZXY",
      "email": "designer@example.com"
    }
  }
}

All webhook payloads are JSON-formatted with event metadata and the updated resource's current state.

Securing Your Endpoints

HMAC Verification

• Extract the X-Hub-Signature-256 header
• Compute a SHA256 HMAC of the payload with your secret
• Compare the computed and received signatures

View code example →

Rate Limiting

✓ Webhooks don't count against regular rate limits
✓ System enforces per-webhook delivery limits
✓ Excess events will be queued and retried

Signature Verification (Node.js)


const crypto = require('crypto');

function verifySignature(body, signatureHeader, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(body)).digest('hex');
  const expectedSignature = 'sha256=' + digest;
  
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expectedSignature)
  );
}

Implementation Tips

• Store secrets securely in environment variables
• Use crypto.timingSafeEqual() to avoid timing attacks
• Require valid signatures for all event types
• Return 401 for invalid signatures

Listing and Deleting Webhooks

List All Registered Webhooks


curl -X GET https://api.example.com/webhooks \
-H "Authorization: Bearer YOUR_API_TOKEN"

This returns a list of active webhooks including their configuration details, last delivery status, and subscription history.

Project Docs