Webhooks API

Hakona can send outbound webhook notifications to your own endpoints whenever workflow runs complete, fail, or change state.

Creating a webhook

POST /v1/webhooks

Request body

{
  "url": "https://your-server.com/hakona-events",
  "events": ["run.succeeded", "run.failed"],
  "workflow_id": "wf_abc123"
}

Omit workflow_id to receive events for all workflows.

Supported events

Event	Fired when
run.started	A workflow run begins
run.succeeded	A run completes successfully
run.failed	A run fails after all retries are exhausted
workflow.activated	A workflow is deployed
workflow.paused	A workflow is paused

Webhook payload

{
  "event": "run.failed",
  "timestamp": "2026-04-29T09:05:00Z",
  "data": {
    "run_id": "run_def456",
    "workflow_id": "wf_abc123",
    "workflow_name": "Notify on GitHub issue",
    "error": "Action 'Post to Slack' failed: channel_not_found"
  }
}

Verifying webhook signatures

Every request includes an X-Hakona-Signature header — an HMAC-SHA256 signature of the raw request body using your webhook's signing secret.

import hmac, hashlib

def verify(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

List webhooks

GET /v1/webhooks

Delete a webhook

DELETE /v1/webhooks/{id}