Webhooks

Webhooks tell another system when something happens in a project: a spec landed, a build failed, a docs release went out. Send them to Slack, Discord, or any HTTPS endpoint.

Find them in Project settings, under Webhooks.

Adding one

Press New webhook

Choose a destination: Slack, Discord or a generic HTTPS endpoint.
Add a label and URL

The URL must start with https://. The label is just for you.
Pick the events

Forward only what you need, or use Select all.
Save the secret

Octri shows a signing secret after you create the webhook. You use it to verify deliveries.

Press Send test to check it works, and Deliveries to see each attempt and whether it succeeded.

Events

Event	Fires when
`spec.ingested`	A spec has been imported
`spec.validation_failed`	A spec could not be validated
`spec.update_detected`	Spec sync found a new version
`doc.generated`	Endpoint pages have been generated
`doc.edited`	An endpoint page was edited
`changelog.generated`	A new changelog was written
`guide.created`	A page was created
`guide.updated`	A page was updated
`guide.deleted`	A page was deleted
`guide.published`	A page was published
`docs.release_published`	A docs release went live
`deployment.failed`	A deployment failed
`chat.session.created`	A reader started an AI chat
`ai.limit_reached`	The project hit its AI limit
`sdk.build_completed`	An SDK build finished
`sdk.build_failed`	An SDK build failed
`sdk.published`	An SDK was published
`sdk.publish_failed`	An SDK could not be published

What a generic webhook receives

A generic endpoint gets a JSON POST with these headers:

Header	Value
`User-Agent`	`octri-webhook/1`
`X-DocsPlatform-Event`	The event name
`X-DocsPlatform-Signature`	The signature, described below
`X-DocsPlatform-Delivery`	The attempt number

Verifying a delivery

The signature is the hex HMAC-SHA256 of the raw request body, using your webhook's secret. Compute it yourself and compare in constant time before trusting the payload.

import { createHmac, timingSafeEqual } from "node:crypto";

function isFromOctri(rawBody, header, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  return (
    header.length === expected.length &&
    timingSafeEqual(Buffer.from(header), Buffer.from(expected))
  );
}

Verify the raw bytes you received, before parsing them. Parsing and re-serializing the JSON can change the bytes and break the match.

Retries and failures

A failed delivery is tried up to four times in all, with a growing delay between attempts. Redirects are followed, up to three.

After ten failures in a row, Octri turns the webhook off and marks it Auto-disabled. Fix the endpoint, then turn it back on.

From the CLI

Webhooks can be created, tested and updated, and their deliveries read, with octri webhooks.