Webhook API

The primary endpoint for receiving webhooks.

Trigger a hook

POST /hook/{slug}

Request

curl -X POST http://localhost:8080/hook/deploy \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"repo": "myapp", "branch": "main"}'

Responses

200 OK — Execution started:

{
  "execution_id": "01HQXYZ..."
}

200 OK — Filtered by trigger rule:

{
  "status": "filtered",
  "reason": "cooldown: 3m remaining"
}

400 Bad Request — Malformed JSON:

{
  "error": "invalid JSON"
}

401 Unauthorized — Authentication failed:

{
  "error": "authentication failed"
}

404 Not Found — No hook with that slug (or hook is disabled).

422 Unprocessable Entity — Payload validation failed:

{
  "error": "payload validation failed",
  "details": ["missing required field: repo"]
}

429 Too Many Requests — Rate limit exceeded:

{
  "status": "rate_limited",
  "reason": "rate limit exceeded: 10/min"
}

Headers