Skip to main content
Docs
Browse documentation

Guide

Webhooks

Receive durable project events with signed, retryable HTTPS deliveries.

On this page
  1. Prerequisites
  2. Create an endpoint
  3. Expected result
  4. Errors
  5. Next step

Prerequisites

Use a server API key with webhooks:manage, an HTTPS endpoint that can read the unmodified request body, and durable storage for processed event IDs. Local or private network targets are rejected in production.

Create an endpoint

Create the endpoint in the console or API and store the one-time signing secret in your secret manager.

bash
curl https://api.moiraconnect.com/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer $MOIRA_API_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://example.test/moira-events","event_filters":["message.*"]}'

Verify the signature against the raw body before parsing JSON. Return a success status quickly and move business work to your own durable queue.

event_filters accepts exact event names, family wildcards, or *. A wildcard matches the family an event is named after: messaging is message.*, connection lifecycle is account.*, backfills are sync.*, source control is github.*, and error tracking is telemetry.* (telemetry.issue.*, telemetry.error.created, telemetry.alert.triggered, telemetry.comment.created). sentry.* matches only the command-settlement events sentry.action.completed and sentry.action.failed — it does not deliver issues. Edit an endpoint's filters from its page in the console or with PATCH /v1/webhooks/{id}.

Expected result

Each matching event produces a delivery record. Retries preserve the event identity, and the console exposes outcome, attempt, response status, and redacted failure information.

Errors

  • 422 validation_error means the target URL or event filter is invalid.
  • A disabled endpoint needs operator review before deliveries resume.
  • A repeated idempotency key with different input returns 409 idempotency_conflict.

Next step

Send a test event, confirm one verified delivery, and add an alert for sustained failures.