Configure webhooks

Connect Kera with external services using webhooks. Send events out when tickets change, and receive events from GitHub, GitLab, and other tools.

Outbound webhooks

Kera sends HTTP POST requests to external services when workflow transitions fire.

  1. 1 Register the webhook

    Create an outbound webhook with a name and a target URL, in workspace settings or with the create_outbound_webhook MCP tool. Kera shows the signing secret once, so store it where your receiver can read it.

  2. 2 Add a webhook action to a transition

    In your workflow YAML, add a send_webhook action that names the webhook. Kera sends a POST every time the transition fires. event is optional and defaults to ticket.transitioned.

    transitions: - from: in_progress to: review actions: - type: send_webhook webhook: ci event: ticket.ready_for_review

  3. 3 Understand the payload

    Each request is a JSON POST with the ticket, the state change, and who made it.

    // Outbound webhook payload { "event": "ticket.ready_for_review", "delivery_id": "…", "ticket": { "id": "5f1c2a9e-…", "key": "KERA-42", "title": "Fix login timeout", "reporter": "alex@example.com", "assignee": "max@example.com", "state": "review", "prev_state": "in_progress" }, "workspace_id": "…", "project_slug": "kera", "actor": "max@example.com", "occurred_at": "2026-04-24T10:30:00Z" }

  4. 4 Verify the signature

    Every request carries X-Kera-Signature: sha256=<hex>, an HMAC-SHA256 of the raw body keyed with your signing secret. Compute it on your side and reject requests that don't match. Kera also sends X-Kera-Event, X-Kera-Webhook-Id, X-Kera-Delivery-Id, and X-Kera-Delivery-Attempt, plus any custom headers you configured.

  5. 5 Common use cases

    Trigger CI/CD pipelines when tickets move to review, notify a Slack channel when tickets are done, or sync state with an external tracker.

Inbound webhooks

External services send events to Kera to auto-link PRs, update ticket status, and sync pipeline results.

  1. 1 Set up an integration

    Go to your workspace settings and add an integration for GitHub or GitLab. Each integration creates a unique webhook URL.

  2. 2 Copy the webhook URL

    Each integration gets a unique endpoint:

    https://your-workspace.getkera.eu/webhooks/inbound/{slug}/{token}

  3. 3 Configure your source

    In GitHub or GitLab, add the webhook URL to your repository settings. Select the events you want to send (push, pull request, pipeline, etc.).

  4. 4 Automatic linking

    Once configured, Kera automatically links PRs to tickets by matching branch names and commit messages. It updates ticket status on merge and syncs pipeline results.

Tips

  • Inbound webhooks are verified via signature (GitHub) or token (GitLab) — unverified requests are rejected.
  • Outbound deliveries are retried with increasing delays after a network error or a 5xx response, up to the webhook's retry limit (5 by default). A 4xx response is not retried. The final outcome of each delivery appears in the audit trail.
  • The same delivery can arrive more than once, after a retry or a resend. Your receiver must dedupe on X-Kera-Delivery-Id (also in the signed body as delivery_id): it stays the same across every retry and resend of one delivery, and differs between two deliveries of the same event. X-Kera-Delivery-Attempt changes on each retry, so don't dedupe on it.
  • The older inline form, url: instead of webhook:, sends a single unsigned request with no retries. Prefer a registered webhook.
  • You can add multiple send_webhook actions to a single transition to notify several services at once.

Next steps