Webhooks

Dojo can send HTTP webhooks when events occur in your repositories. Webhooks are signed with HMAC-SHA256 for security and support filtering by branch and event type.

Create a webhook

POST /api/repos/{owner}/{name}/hooks

{
  "url": "https://your-server.com/webhook",
  "secret": "your-webhook-secret",
  "events": ["push", "stack.submitted", "stack.merged"],
  "branch_filter": "main",
  "active": true
}

Parameters:

Field	Required	Description
url	✅	HTTPS endpoint to receive webhooks
secret	✅	Shared secret for HMAC-SHA256 signature
events	—	Event types to subscribe to (default: all)
branch_filter	—	Only trigger for matching branch names (glob supported)
active	—	Enable/disable (default: true)

Events

Event	Description
push	Commits pushed to a ref
stack.submitted	Stack submitted for review
stack.merged	Stack merged
review.approved	Stack approved by reviewer
review.rejected	Changes requested on stack
review.commented	Comment left on stack
workspace.created	New workspace created
workspace.committed	Workspace committed

Webhook delivery

Webhooks are delivered as POST requests with:

Headers

Header	Description
Content-Type	application/json
X-Dojo-Event	Event type (e.g., push)
X-Dojo-Signature	HMAC-SHA256 signature of the body
X-Dojo-Delivery	Unique delivery ID

Verifying signatures

import { createHmac } from "crypto";

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return `sha256=${expected}` === signature;
}

Payload

{
  "event": "push",
  "repository": {
    "owner": "mies",
    "name": "dojo"
  },
  "ref": "main",
  "commits": [
    {
      "commit_id": "abc123...",
      "message": "feat: add search API",
      "author_name": "claude",
      "timestamp": 1707500000
    }
  ],
  "timestamp": 1707500000
}

Managing webhooks

# List webhooks
GET /api/repos/{owner}/{name}/hooks

# Update a webhook
PATCH /api/repos/{owner}/{name}/hooks/{hookId}

# Delete a webhook
DELETE /api/repos/{owner}/{name}/hooks/{hookId}

# View delivery history
GET /api/repos/{owner}/{name}/hooks/{hookId}/deliveries

Retry policy

Failed deliveries (non-2xx responses) are logged but not automatically retried. Check the delivery history endpoint for failed deliveries.