For AI agents: this page as Markdown is at https://frazer.ai/docs/webhooks.md. Indexes for agents: https://frazer.ai/docs/api/llms.txt and https://frazer.ai/llms.txt.
Frazer sends an event for every change that matters: a server joined, a rollout succeeded, a backup failed, an agent
waits for an approval, an invoice was paid. A webhook endpoint receives these events as CloudEvents-shaped JSON, signed
with Standard Webhooks and delivered at least once, with retries for about 3 days. Events carry identifiers and
states, never secret values.
Event type: ai.frazer.<service>.<resource>.v1.<pastVerb>: the service (such as releases, kubernetes or
monitoring), the resource in it, the version and what happened. For example, ai.frazer.releases.rollout.v1.succeeded. Each type has a JSON Schema in the event catalog.
Endpoint: a URL in a project (projects/{project}/webhookEndpoints/{endpoint}) with the event types it receives,
a format, its signing secrets and a status: enabled, failing or disabled.
Event sink: delivery for a whole organization, aggregated over its projects
(organizations/{organization}/eventSinks/{sink}).
Delivery: every attempt to send one event to one endpoint, kept in the delivery log with the request, the
response and the latency.
Each event has the CloudEvents 1.0 attributes id, source, type, specversion, time and subject, plus
data. By default data is a snapshot of the resource at the time of the event. An endpoint can ask for thin
events instead, which carry only identifiers; you fetch the rest with the API.
Create the endpoint and choose its events. A pattern such as ai.frazer.releases.rollout.v1.* matches every rollout event. Match on IDs (organizationId, projectId), never on display names.
Open the project’s Settings › Integrations and its Webhooks tab, add an endpoint, enter the URL and choose
the event types and the format. For every project at once, use the organization’s
Settings › Integrations › Webhooks.
Store the endpoint’s signing secret in your receiver. It starts with whsec_.
Send a test event. In the console, choose Send test event on the endpoint, or run:
Every request carries three headers. webhook-signature holds one or more space-separated signatures of the form
v1,<base64>: an HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}, keyed with your secret (the base64 part
after whsec_).
Answer with a 2xx status within 15 seconds; do slow work after you answer. A 3xx counts as a failure. Frazer makes up to
10 attempts, about 3 days in all, and stops at the first success:
Attempt
After the previous attempt failed
1
Immediately, when the event happens
2
5 seconds
3
5 minutes
4
30 minutes
5
2 hours
6
5 hours
7
10 hours
8
10 hours
9
24 hours
10
24 hours
Delivery is at least once and unordered. Deduplicate on webhook-id: a redelivery keeps the same webhook-id.
When order matters, compare each event’s time, or fetch the resource’s current state with the API.
To stop the retries for one message, answer with the header webhook-delivery: abort-message.
After 3 failed attempts, the endpoint’s owner gets an email. After 5 days of failures, the endpoint is disabled, an
email goes out, and your other endpoints receive frazer.webhook.endpoint_disabled.v1.
When you rotate an endpoint’s signing secret, the new secret signs alongside the old one for 24 hours, then the old
one stops. During those 24 hours each request carries two v1 signatures: deploy the new secret to your receiver, and
the code above accepts either.
Frazer sends from fixed egress addresses, IPv4 and IPv6, published with their reverse DNS names in
frazer.ai/egress-ips.json. Webhooks prefer IPv4. An endpoint can choose IPv6 or either family instead
(source_family: PREFER_IPV4, IPV6 or ANY).
Endpoint URLs are resolved through Frazer’s egress proxy. A URL that resolves to a private, link-local or metadata
address is refused, and DNS is checked again when Frazer connects.
Endpoints belong to a project; an event sink delivers an organization’s events from all its projects.
Creating, changing, disabling, enabling and deleting endpoints, rotating their secrets and redelivering are audit
events: webhooks.endpoint.create, update, delete, disable, enable, secret_rotate and
webhooks.delivery.redeliver.
Events never carry secret values or log bodies. Untrusted text, such as commit messages and issue titles, is
shortened and marked as untrusted.
An agent that has read untrusted content cannot call a webhook without approval.
The signature does not match. Verify the raw body, not a parsed copy; decode the part of the secret after
whsec_ from base64; check your clock. During a rotation, accept either signature.
An endpoint shows failing. Your receiver answered with an error or a redirect, or took longer than 15 seconds.
Fix it, then redeliver the failures from the log.
An endpoint is disabled. It failed for 5 days. Fix the receiver, enable the endpoint again and redeliver
everything that failed since the first failure.
The same event arrived twice. Delivery is at least once. Deduplicate on webhook-id.
Events arrive out of order. Delivery is unordered. Compare time, or fetch the current state with the API.
The endpoint URL is refused. It resolves to a private, link-local or metadata address. Use a public address.
Requests never reach a receiver behind an allowlist. Allow the addresses in frazer.ai/egress-ips.json; webhooks
use IPv4 unless the endpoint says otherwise.
Events carry only IDs. The endpoint uses the thin format. Switch it to snapshot, or fetch each resource with the
API.
Every event type Frazer sends, by product, exactly as it arrives in the type attribute. An endpoint subscribes to
exact types or to a pattern such as ai.frazer.releases.rollout.v1.*.
An endpoint was disabled after 5 days of failed deliveries.
frazer.approval.requested.v1
A change is waiting for an approval.
frazer.approval.decided.v1
An approval was decided.
frazer.plan.applied.v1
An approved plan was applied.
frazer.audit.event.v1
An audit record was written; for a SIEM.
The API is WebhookEndpointsService (with deliveries, redeliver, send test and rotate secret) and EventTypesService,
which serves each event type’s JSON Schema. On mcp.frazer.ai, webhook tools are in the toolset webhooks.