Quartz 5

Lab: Docs, release/API publication, and signed webhooks

Properties1
tagslab, az-400, documentation, mermaid, release-notes, api, webhooks

3 min read

Lab: Docs, release/API publication, and signed webhooks

Outcome

Publish a small Markdown wiki page with a Mermaid process diagram, generate and review release/API documentation for a tagged training release, and validate signed GitHub webhook deliveries at a disposable endpoint.

Do: docs and release evidence

  1. Create an Azure DevOps project wiki or publish a documentation repository as a wiki. Add release-process.md with ownership, prerequisites, deployment/rollback steps, and this diagram:

    sequenceDiagram
  participant Dev as Developer
  participant CI as CI
  participant Rel as Release
  Dev->>CI: Pull request
  CI-->>Dev: Required checks
  Dev->>Rel: Tag and publish

  2. View the rendered page. Deliberately replace sequenceDiagram with unsupported or malformed syntax, observe the render failure, correct it, and re-render. Azure DevOps supports standard fenced Mermaid syntax, but supported diagram syntax is not unlimited.

  3. From a tagged training release, create release notes that name version, included PRs/commits, known issues, rollback, owner, and links. Publish a small OpenAPI/API document with endpoint, request/response example, authentication boundary, version, and deprecation rule. Verify the published release and documentation URLs; correct one intentionally inaccurate generated entry before publication.

Do: signed webhook delivery

  1. Deploy or select a disposable HTTPS receiver that logs only event ID, event type, status, and signature-validation result. Store its webhook secret in a secret store/environment variable, never in source or logs.
  2. Configure a GitHub repository webhook for one harmless event, set the secret, deliver a test event, and inspect the delivery ID/payload metadata and receiver result. Validate X-Hub-Signature-256 by computing HMAC-SHA-256 on the raw UTF-8 body and comparing in constant time.
  3. Send a deliberately altered body or use a wrong secret in the disposable receiver. Verify rejection before event processing, restore the valid secret/body, and confirm an accepted redelivery. Add retry/idempotency handling keyed by delivery ID.

Verify

Capture rendered wiki/diagram, malformed-diagram correction, tagged release and corrected notes, published API document, webhook configuration without secret exposure, delivery log, accepted signature, and rejected altered signature. You should now understand: Markdown source is not proof of a rendered document; release notes require human review; a webhook receiver must authenticate the raw delivery before acting on it.

Break and fix

  1. Publish an invalid Mermaid diagram; use rendered error/context to fix syntax.
  2. Include an incorrect commit or undocumented breaking API change in generated notes; correct the source/release document and obtain review before publishing.
  3. Use an invalid webhook secret or altered payload; verify constant-time signature rejection, correct the secret, and redeliver safely.

Scenario practice

  1. Configure: Define documentation owner, version/release-note/API-review gates, wiki publication path, webhook event scope, secret storage, and retry/idempotency rule.
  2. Diagnose: A diagram fails to render, release notes omit a breaking change, or a webhook returns 401. Inspect syntax support, tag/range/input review, raw body, header, secret, and receiver logs.
  3. Distinguish: Contrast wiki source with rendered documentation, release notes with API reference, generated history with reviewed release claims, and webhook delivery with an authenticated API request.

Clean up

Delete the training wiki/page or repository documentation as appropriate, release/tag only if disposable, webhook, receiver, delivery logs, and secret. Rotate the secret immediately if it was exposed outside the test receiver.

Sources and re-audit

Re-audit when wiki rendering, release/API publishing, webhook events, or signature requirements change.

docs-as-code · release-notes-templates · webhooks · github · All labs

Graph View

Backlinks