Response: Webhook Delivery Guide

Deliverable

WEBHOOKS.md is 1,094 words by wc -w, or about 1,030 without table pipes, so it falls inside the 700–1,100 target. It covers every required element:

• a request/header reference
• a minimal verification example
• response rules
• retry semantics
• ordering and idempotency
• key rotation
• operations advice
• a troubleshooting table

I ran the Python verifier locally against these cases:

• A valid signature made with the second of two secrets is accepted.
• A signature made with the wrong secret is rejected.
• A body changed by a single byte is rejected.
• A non-ASCII signature header is rejected; it does not raise an exception.

Editorial choices

1. Three explicit labels. Every section separates Guarantee (behavior stated in the notes), Recommendation (our advice), and Unconfirmed (open questions). Readers can then tell what they may build on.
2. Signature conflict resolved toward the current implementation. The guide documents timestamp + "." + raw body as current behavior. A callout says the older "parsed JSON" description is stale. I did not describe the old scheme as a supported alternative.
3. Conservative stance on timestamp freshness. The notes give no tolerance window. Retries can arrive up to about 15 h late and replays up to 7 days late. Rejections return a non-retried 4xx. For those reasons I did not recommend a typical 5-minute window, which could silently drop legitimate events. The guide tells readers to log timestamp age until behavior is confirmed.
4. Unsigned event ID pointed out. The signature covers only the timestamp and body. The X-Orbit-Event header can therefore be altered, and the guide says so.
5. Consequences drawn from stated facts, not new behavior. Some advice follows directly from the notes; none of it describes new behavior:
   • Signature failures return 401, which is not retried, so readers should alert and replay.
   • Deduplication will swallow manual replays, because replays reuse the event ID.
   • Readers should return 503 for transient errors.
   • The rotation procedure is robust to either signing behavior during the overlap.
6. "Roughly" kept as "approximate". Retry times are not presented as exact. The count is stated precisely: 5 retries, 6 attempts in total.
7. Redirects are treated as unconfirmed. The advice to register the final URL is safe whatever the answer turns out to be.
8. HTTPS is given only as a recommendation, because the notes don't say whether plain HTTP is allowed.
9. Payload schema omitted. The notes don't describe body fields, so the guide invents none. That includes an in-body event ID or a creation time for ordering.
10. Logging warning. The guide warns against logging secrets, signature headers, or full sensitive payloads, as the notes request.

Unresolved questions for product/engineering

1. Signing scheme. Confirm that the old "sign parsed JSON" scheme is gone for every endpoint, including legacy ones. Confirm that the hex is lowercase.
2. Timestamp on retries and replays. Is the request signed again with a new X-Orbit-Timestamp? What freshness window should we recommend?
3. Does X-Orbit-Timestamp reflect event creation or send time?
4. Event ID in the body. Does the signed body contain the event ID, so that deduplication can rely on a signed value?
5. Retries and the event ID. Confirm that retries reuse the event ID. The notes state this only for replays; the guide assumes it for retries.
6. Retry intervals. Are they relative to the previous attempt or to the first one? How much jitter is there? Is Retry-After honored?
7. After the final retry. Is the endpoint disabled or the customer notified? Can the event still be replayed?
8. 3xx and 1xx responses. How are they classified: failure, retried, or not retried?
9. Redirects. Are they followed? Security says no; the implementation owner has not confirmed.
10. Rotation overlap. During the 24 h window, does Orbit sign with the current secret, the previous one, or both? Can X-Orbit-Signature contain multiple v1= values? Is the new secret shown once, like the original?
11. Replay window. Are the 7 days measured from event creation or from the first delivery? Are replays subject to the same retry policy?
12. Oversized payloads. What happens to events over 512 KiB: are they dropped, truncated, or sent as a reference?
13. Plain HTTP endpoints. Are they permitted?
14. Content-Type. What is the exact Content-Type header value?

Raw webhook notes

• POST JSON. Event id in X-Orbit-Event; event type X-Orbit-Type.
• signature header X-Orbit-Signature: v1=<hex> using HMAC SHA-256 over raw bytes. Secret shown once. Comparison constant-time.
• docs from old system say sign parsed JSON; this is probably stale. Current implementation signs timestamp + dot + raw body. Timestamp header is X-Orbit-Timestamp Unix seconds. Need state that old note conflicts.
• retry on timeout, network error, 408, 425, 429, and 5xx. Do not retry other 4xx. Schedule roughly 1m, 5m, 30m, 2h, 12h. Five retries after initial try.
• receiver has 10 seconds to return any 2xx. Response body ignored.
• duplicates possible. Delivery order usually follows creation but concurrent retries mean it is not guaranteed.
• secret rotation: two secrets valid for 24 hours; UI labels current/previous.
• replay UI can resend an event for 7 days and uses same event id.
• payload max 512 KiB. User-Agent Orbit-Hooks/2.
• uncertain: are redirects followed? Security thinks no, implementation owner has not confirmed.
• examples should warn against logging secrets or full sensitive payloads.

Task 05 — Technical writing: webhook delivery guide

Turn SOURCE_NOTES.md into WEBHOOKS.md, a developer guide for customers integrating with the service. Target 700–1,100 words.

The guide must include a minimal verification example, delivery and retry semantics, ordering/idempotency guidance, key rotation, operational advice, and a troubleshooting table. Clearly distinguish guarantees from recommendations. Resolve apparent contradictions conservatively and call out anything that still requires product confirmation instead of inventing behavior.

Write RESPONSE.md with your editorial choices and unresolved questions. Work only in this directory.

Receiving Orbit Webhooks

This guide covers how to verify, acknowledge, and process Orbit webhook deliveries. Statements are labelled:

• Guarantee: current delivery behavior you can build on.
• Recommendation: our advice. Orbit does not enforce it.
• Unconfirmed: an open question. Don't depend on either answer.

The request

Guarantee. Each delivery is a POST with a JSON body of at most 512 KiB, carrying these headers:

Header	Contents
X-Orbit-Event	Event ID. Retries and manual replays of an event reuse it.
X-Orbit-Type	Event type
X-Orbit-Timestamp	Unix time in seconds, part of the signed content
X-Orbit-Signature	v1=<hex>: an HMAC-SHA256 signature
User-Agent	Orbit-Hooks/2

Recommendation. Every layer in front of your handler (load balancer, proxy, framework) should accept bodies of at least 512 KiB. Don't treat User-Agent as authentication.

Verifying the signature

Guarantee. Orbit computes HMAC-SHA256 using your endpoint's signing secret over:

<X-Orbit-Timestamp value> + "." + <raw request body bytes>

It sends the hex digest as X-Orbit-Signature: v1=<hex>.

Conflicting older documentation. Documentation from the previous system says the signature covers the parsed JSON. That is out of date. Re-serializing JSON changes key order and whitespace, so verification will fail.

A minimal verifier in Python, using only the standard library:

import hashlib
import hmac

def verify_orbit_signature(raw_body: bytes, headers, secrets: list[str]) -> bool:
    """headers: a case-insensitive mapping. secrets: every currently valid secret."""
    timestamp = headers.get("X-Orbit-Timestamp", "")
    signature = headers.get("X-Orbit-Signature", "")
    if not timestamp or not signature.startswith("v1="):
        return False
    received = signature[3:].strip().lower().encode("utf-8")
    signed = timestamp.encode("utf-8") + b"." + raw_body
    for secret in secrets:
        expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
        if hmac.compare_digest(expected.encode("ascii"), received):  # constant-time
            return True
    return False

Recommendations:

• Read the raw body before any JSON middleware runs, and verify before you act on the payload.
• Compare in constant time, never with ==.
• Reject failures with 401. That status isn't retried, so alert on failures: a wrong secret silently drops events until you replay them.
• Never log the secret or the signature header.

Unconfirmed: timestamp freshness. Whether retries and replays get a fresh timestamp is unconfirmed. Retries can arrive about 15 hours after the first attempt and replays up to 7 days later, so a short freshness window could reject legitimate deliveries permanently. Until Orbit confirms, log timestamp age instead of rejecting on it. X-Orbit-Event is not signed, so event-ID deduplication alone won't stop a captured request being replayed.

Responding

Guarantee. Return any 2xx status within 10 seconds. Orbit ignores the response body.

Recommendation. Verify the signature, store or enqueue the event, return 200, and then process it asynchronously. Slow inline processing causes timeouts and duplicates.

Delivery and retries

Guarantees:

Outcome of an attempt	Retried?
Timeout (no 2xx within 10 s) or network error	Yes
408, 425, 429, any 5xx	Yes
Any other 4xx	No
2xx	Delivered, not retried

• Orbit makes up to five retries after the initial attempt (six attempts in total).
• Retries follow an approximate schedule of 1 min, 5 min, 30 min, 2 h, and 12 h.

Recommendations. Use 4xx only for requests that will never succeed. For temporary problems, such as a database outage, return 503.

Unconfirmed:

• Whether each interval is measured from the previous attempt (about 14.6 h in total) or from the first attempt.
• Whether Retry-After is honored on 429/503.
• What happens after the last retry fails (endpoint disabled? notification?).
• Redirects. Security believes they aren't followed; the implementation owner hasn't confirmed. Register the exact final HTTPS URL.

Ordering and idempotency

Guarantees:

• Duplicates are possible.
• Order is not guaranteed. Deliveries usually arrive in the order the events were created, but concurrent retries can reorder them.

Recommendations:

• Deduplicate on the event ID. Keep processed IDs for longer than the 7-day replay window.
• Record an ID only after processing succeeds, ideally in the same transaction as your side effects, so a failed delivery can still be retried or replayed.
• Replays reuse the event ID, so deduplication skips already-processed events. To reprocess one deliberately, clear its record first.
• Don't infer order from arrival time or from X-Orbit-Timestamp. Whether it reflects event creation or signing time is unconfirmed. Check your own current state before applying a change.

Rotating the signing secret

Guarantees:

• A secret is displayed only once. Copy it to your secret store immediately.
• After you rotate, the new secret (labelled current) and the old one (previous) are both valid for 24 hours.

Unconfirmed: during that overlap, which secret Orbit signs with, and whether a header can carry more than one signature. The following procedure works in every case:

1. Rotate in the dashboard and store the new secret.
2. Deploy immediately with both secrets in secrets.
3. Confirm that deliveries verify.
4. After 24 hours, remove the previous secret.

Replay any deliveries rejected between steps 1 and 2.

Operations

• Replay: the dashboard can resend an event for up to 7 days (guarantee).
• Transport: use HTTPS (recommendation).
• Logging: log event ID, type, status, and latency. Don't log secrets, signatures, or full payloads that may contain sensitive data.
• Monitoring: alert on signature failures, non-2xx rates, and handler latency approaching 10 seconds.

Troubleshooting

Symptom	Likely cause	Fix
Every signature fails	Verifying re-serialized JSON, omitting the timestamp, or using the wrong secret	HMAC timestamp + "." + raw bytes with the current secret
Failures start right after rotation	Only one secret configured	Accept both secrets for 24 hours, then replay the failed events
Same event processed twice	Duplicate delivery or retry	Deduplicate on the event ID
Retries arrive even though the handler succeeded	Response took longer than 10 s	Acknowledge first, then process asynchronously
Failed event never retried	Handler returned a non-retryable 4xx	Return 503 for transient errors, then replay
Events arrive out of order	Expected: order isn't guaranteed	Make handlers order-independent
Large events rejected, e.g. with 413	Body limit below 512 KiB	Raise the limit on every layer
Nothing arrives after the URL changed	Possibly a redirect that isn't followed	Register the final URL directly
Replayed event ignored	Deduplication matched the reused ID	Clear the ID's record before replaying

RESPONSE: editorial choices and unresolved questions

Deliverable: WEBHOOKS.md (1,066 words by wc -w, 1,004 excluding the code block; the 700-1,100 target holds either way). The Python example was executed against a synthetic signature and passed with the previous secret, failed without it, and failed on a re-serialized body.

Editorial choices

Labeling. Every claim is tagged Guarantee, Recommendation, or Unconfirmed, with a legend at the top. Anything in the notes stated as fact is a Guarantee. Advice I derived is a Recommendation. Anything the notes flag as uncertain, or that I would have had to infer, is Unconfirmed and repeated in an "Open items" list.

Signing contradiction (resolved conservatively). The notes say the old docs sign parsed JSON and that this is "probably stale", while the current implementation signs timestamp + "." + raw body. The guide documents the current scheme as the only scheme, states explicitly that the older docs conflict, and tells readers not to add a parsed-JSON fallback (it would accept a scheme we do not claim to support). The first bullet's "HMAC SHA-256 over raw bytes" is read as the raw-body part of the same scheme, not a separate one. The example uses the X-Orbit-Timestamp header string verbatim, which avoids inventing a timestamp format.

"Comparison constant-time." The senders do not compare anything, so I read this as a receiver instruction and made it a Recommendation, implemented with hmac.compare_digest.

Retry arithmetic. "Five retries after initial try" and five listed intervals agree (six attempts total). "Roughly" is preserved as "approximate". The roughly 14.5-hour span is my sum of the intervals and is marked Unconfirmed, because the notes do not say whether intervals run from the previous attempt.

Delivery is not guaranteed. The notes support at-least-once attempts with duplicates, not guaranteed delivery, so the guide says outright that retries can be exhausted and that recovery is manual replay.

Redirects. Marked Unconfirmed. Security's belief ("no") and the implementation owner's silence are both reported. The reader instruction (register the final URL, never redirect) is safe under either answer, and the guide makes no promise about what Orbit does on a 3xx.

Rotation. The notes say two secrets are "valid for 24 hours" without saying which signs. I made the example accept a list of secrets, and made "accept both" the recommendation, since that is correct whichever secret signs.

Ordering advice. The notes do not describe the payload schema, so I did not invent a sequence or version field. The guide says not to overwrite newer state with older events and not to order by X-Orbit-Timestamp.

Idempotency details. Atomic insert-if-absent and "mark done only after commit" are derived from the notes' facts (concurrent retries, replay with the same event id). They are labeled Recommendations.

Conservative omissions. The guide does not state a timestamp freshness window, a Content-Type, HTTPS enforcement, IP allowlists, Retry-After handling, or which 3xx codes count as failures, because none are in the notes.

Naming. I called the product "Orbit", inferred from the X-Orbit-* headers and the Orbit-Hooks/2 User-Agent. Please confirm.

Support channel. The guide says "contact us" once (early revocation after a suspected compromise) without naming a channel, because the notes name none.

Unresolved questions for product/engineering

1. Redirects. Does the delivery client follow them? Does a 3xx count as a failure, and is it retried?
2. Key format. Is the HMAC key the displayed secret as UTF-8 bytes, or is there a prefix or encoding to strip?
3. Signature header. Can it carry multiple v1= values (for example during rotation)? What happens when a v2 scheme is introduced?
4. Rotation. Which secret signs during the 24-hour overlap? Can the previous secret be revoked early after a compromise? Can rotation be repeated during the overlap?
5. Timestamp semantics. Is X-Orbit-Timestamp regenerated per attempt and per replay, or fixed at event creation? What tolerance, if any, do we recommend for replay protection?
6. Event ID stability. The notes confirm replays keep the event id. Do automatic retries also keep it? The dedupe advice assumes yes.
7. Retry exhaustion. What happens to an event after the sixth failed attempt? Is it marked failed, visible in the dashboard, or does the endpoint get disabled?
8. Replay window. Is the 7 days measured from event creation or from the last attempt? Does a replay get a fresh signature and timestamp, and which secret signs it?
9. Timeout scope. Does the 10-second limit cover connection setup and the full response, or only time to first byte?
10. 429 handling. Is Retry-After honored, or does the fixed schedule apply?
11. Oversize events. What happens to an event whose payload would exceed 512 KiB (rejected, truncated, or sent by reference)?
12. Are the retry intervals jittered, and are intervals measured from the previous attempt?
13. Support channel to reference for compromise or replay issues, and source IP ranges for customers who allowlist.

Raw webhook notes

• POST JSON. Event id in X-Orbit-Event; event type X-Orbit-Type.
• signature header X-Orbit-Signature: v1=<hex> using HMAC SHA-256 over raw bytes. Secret shown once. Comparison constant-time.
• docs from old system say sign parsed JSON; this is probably stale. Current implementation signs timestamp + dot + raw body. Timestamp header is X-Orbit-Timestamp Unix seconds. Need state that old note conflicts.
• retry on timeout, network error, 408, 425, 429, and 5xx. Do not retry other 4xx. Schedule roughly 1m, 5m, 30m, 2h, 12h. Five retries after initial try.
• receiver has 10 seconds to return any 2xx. Response body ignored.
• duplicates possible. Delivery order usually follows creation but concurrent retries mean it is not guaranteed.
• secret rotation: two secrets valid for 24 hours; UI labels current/previous.
• replay UI can resend an event for 7 days and uses same event id.
• payload max 512 KiB. User-Agent Orbit-Hooks/2.
• uncertain: are redirects followed? Security thinks no, implementation owner has not confirmed.
• examples should warn against logging secrets or full sensitive payloads.

Task 05 — Technical writing: webhook delivery guide

Turn SOURCE_NOTES.md into WEBHOOKS.md, a developer guide for customers integrating with the service. Target 700–1,100 words.

The guide must include a minimal verification example, delivery and retry semantics, ordering/idempotency guidance, key rotation, operational advice, and a troubleshooting table. Clearly distinguish guarantees from recommendations. Resolve apparent contradictions conservatively and call out anything that still requires product confirmation instead of inventing behavior.

Write RESPONSE.md with your editorial choices and unresolved questions. Work only in this directory.

Orbit Webhooks: Delivery Guide

This guide covers how Orbit delivers webhooks, how to verify them, and how to build a receiver that tolerates retries, duplicates, and reordering.

Statements are labeled:

• Guarantee: behavior Orbit commits to. You can depend on it.
• Recommendation: our advice. Nothing enforces it.
• Unconfirmed: not yet confirmed by Orbit product or engineering. Do not build on it. See Open items.

Request format

Guarantee. Each delivery is an HTTP POST with a JSON body of at most 512 KiB and the User-Agent Orbit-Hooks/2.

Header	Value
X-Orbit-Event	Unique event ID (not the event type)
X-Orbit-Type	Event type
X-Orbit-Timestamp	Unix time in seconds
X-Orbit-Signature	v1=<hex> HMAC-SHA-256 signature

Recommendation. Make sure your framework and any gateway in front of it accept bodies up to 512 KiB. Do not authenticate by User-Agent; verify the signature.

Verify signatures

Guarantee. The signature is the hex HMAC-SHA-256, keyed with your signing secret, of the X-Orbit-Timestamp value, a literal ., and the raw request body bytes:

v1=<hex( HMAC_SHA256(secret, timestamp + "." + raw_body) )>

Conflict with older docs. Documentation from the previous system says to sign the parsed JSON. That is stale and contradicts the current implementation. Follow this guide, and do not add a parsed-JSON fallback.

import hashlib, hmac

def verify(raw_body: bytes, headers, secrets: list[bytes]) -> bool:
    sent = headers["X-Orbit-Signature"]
    if not sent.startswith("v1="):
        return False
    signed = headers["X-Orbit-Timestamp"].encode() + b"." + raw_body
    for secret in secrets:  # current + previous during rotation
        expected = "v1=" + hmac.new(secret, signed, hashlib.sha256).hexdigest()
        if hmac.compare_digest(expected.encode(), sent.encode()):
            return True
    return False

• Recommendation. Read the raw bytes before any JSON parsing or middleware.
• Recommendation. Compare in constant time, as above. Reject failures with a 4xx; it will not be retried.
• Unconfirmed. We assume the key is the secret exactly as displayed, as UTF-8 bytes, and that the header carries a single v1= value.

Delivery and retries

Guarantees

• A delivery succeeds only if your endpoint returns a 2xx within 10 seconds. The response body is ignored.
• Orbit retries after a timeout, a network error, or a 408, 425, 429, or 5xx response.
• Orbit does not retry any other 4xx.
• There are up to five retries after the first attempt, at roughly 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. Intervals are approximate.
• The dashboard can replay an event for 7 days. A replay uses the same event ID.

Retries are not a delivery guarantee. Once they are exhausted, Orbit does not resend automatically. If each interval runs from the previous attempt, the last retry lands about 14.5 hours after the first attempt (Unconfirmed).

Unconfirmed: redirects. Security review believes redirects are not followed; the implementation owner has not confirmed. Register your final URL and never answer with a redirect.

Ordering, duplicates, and idempotency

Guarantee. Duplicates are possible. Delivery order usually follows creation order, but concurrent retries mean order is not guaranteed.

Recommendations

1. Deduplicate on X-Orbit-Event. Use an atomic insert-if-absent (for example a unique constraint), because duplicate deliveries can arrive concurrently.
2. Mark an event done only after your processing commits. If you record it on receipt and processing then fails, the retry or replay is discarded as a duplicate.
3. Do not let an older event overwrite newer state, and do not infer order from arrival time or X-Orbit-Timestamp (its meaning on retries is unconfirmed).
4. Expect replays to look like duplicates. Idempotent handlers make them safe.

Key rotation

Guarantee. After a rotation, two secrets are valid for 24 hours. The dashboard labels them current and previous. A secret is shown only once.

Recommended procedure

1. Rotate and copy the new secret immediately.
2. Deploy a receiver that tries both secrets, as in the example.
3. After 24 hours, check for verification failures, then remove the previous secret.

Unconfirmed. Which secret signs during the overlap, so accept both. Also whether the previous secret can be revoked early; if you suspect compromise, contact us.

Operating your endpoint

• Recommendation: acknowledge fast. Verify, durably enqueue, return 200 or 204, then process asynchronously. Ten seconds is a ceiling.
• Recommendation: choose status codes deliberately. Use 5xx for temporary trouble you want retried. A 4xx caused by your own misconfiguration (a 401 from a wrong secret, say) is not retried; fix it, then replay.
• Recommendation: monitor. Alert on non-2xx rates and signature failures. After an outage longer than the retry span, replay missed events within 7 days.
• Recommendation: protect data. Never log signing secrets or commit them to source control. Avoid logging full payloads, which may be sensitive. Log event ID, type, and outcome.

Troubleshooting

Symptom	Likely cause	Fix
Every signature fails	Following old docs (parsed JSON), or omitting the timestamp	Sign timestamp + "." + raw_body
Only some signatures fail	Middleware altered or re-serialized the body	Capture raw bytes before parsing
Failures right after rotation	Only one secret configured, or a truncated copy	Accept both secrets for 24 hours
Same event processed twice	No deduplication, or a check-then-insert race	Atomic dedupe on X-Orbit-Event
Events arrive out of order	Ordering is not guaranteed	Make handlers order-tolerant
Endless retries	No 2xx within 10 seconds, or a 5xx/429	Return 2xx early; process asynchronously
Event never retried	Your endpoint returned a non-retryable 4xx	Fix it and replay within 7 days
413 or truncated bodies	Gateway limit below 512 KiB	Raise the body limit
Events missing after an outage	Retries exhausted	Replay from the dashboard within 7 days
Redirect response	Endpoint URL moved	Register the final URL (redirect handling is unconfirmed)

Open items

These need product confirmation.

1. Are redirects followed?
2. Secret key encoding, and whether the signature header can carry multiple values.
3. Which secret signs during rotation overlap, and whether early revocation exists.
4. Whether the timestamp is refreshed on retries and replays. Until then, we cannot recommend a freshness window.
5. Whether retries reuse the event ID. Replays do; retries are assumed to.
6. What happens after the final retry fails.

Editorial choices and unresolved questions

Editorial choices

• Organized the customer guide around authentication, acknowledgment and retries, duplicate handling, rotation, and operations, with a troubleshooting table for common failures.
• Used Contract, Recommendation, and Product confirmation labels to distinguish documented service behavior from receiver advice and unresolved details. Approximate timings, usual ordering, and security's redirect expectation are explicitly not guarantees.
• Selected timestamp + dot + unchanged raw body for the verifier because the notes explicitly identify it as the current implementation. Called out both the older parsed-JSON instruction and the abbreviated raw-bytes-only note as conflicting, and requested confirmation of the published signing contract. Did not silently normalize JSON or timestamps.
• Chose a small Python standard-library example to avoid dependencies and framework-specific body handling. It validates the signature shape, compares decoded digests in constant time, and supports both rotation keys without short-circuiting the key comparisons. It receives key bytes rather than inventing the UI secret's encoding.
• Kept timestamp freshness outside the minimal verifier. A five-minute window is only an example recommendation and is conditional on confirmation of retry/replay signing behavior, not an Orbit requirement.
• Explained that the stated signing formula excludes event ID and event type headers. The source recommends neither an authenticated-header mechanism nor a payload schema, so neither was invented.
• Described five automatic retries after the initial attempt as at most six attempts in that sequence. Did not promise ultimate delivery, exactly-once processing, strict ordering, exact retry execution times, or an exhaustion deadline.
• Recommended durable acceptance before acknowledgment, atomic deduplication, and idempotent side effects. The seven-day replay period informs retention advice, with a margin and explicit uncertainty about its starting point and ID scope.
• Included every stated request detail, the 10-second deadline, ignored response body, retryable and nonretryable statuses, replay identity, rotation overlap, payload limit, User-Agent, and sensitive-logging warning. Redirect advice uses a direct endpoint while confirmation remains pending.

Questions for product confirmation

1. Is HMAC-SHA-256 over the exact timestamp header bytes, a literal dot, and the raw body the authoritative signing contract? Can the contradictory legacy documentation be retired? What is the displayed secret's encoding and conversion to key bytes?
2. Are timestamps and signatures regenerated for each automatic retry and manual replay? Is there a supported freshness window or clock-skew allowance?
3. Are redirects followed? Security expects they are not, but the implementation owner has not confirmed this. How are 3xx responses classified for retry purposes?
4. Are the five listed retry timings delays between attempts or offsets from the initial attempt? Is there jitter, and is Retry-After honored? What happens after the final retry? The guide makes no claim about any unlisted scheduling or failure policy.
5. When does the 24-hour rotation overlap start, and which key signs requests during it? Does automatic removal of the previous key occur at a defined time?
6. From which point is the seven-day replay window measured? What is the uniqueness scope of event IDs, and what retention margin covers in-flight deliveries at the replay boundary?
7. Are event ID and type also available within authenticated payload data, or otherwise bound to the signature? What guarantees support trusting these header values for routing and deduplication?

These questions remain open because SOURCE_NOTES.md does not establish their answers. The deliverables document the uncertainties without adding service behavior.

Raw webhook notes

• POST JSON. Event id in X-Orbit-Event; event type X-Orbit-Type.
• signature header X-Orbit-Signature: v1=<hex> using HMAC SHA-256 over raw bytes. Secret shown once. Comparison constant-time.
• docs from old system say sign parsed JSON; this is probably stale. Current implementation signs timestamp + dot + raw body. Timestamp header is X-Orbit-Timestamp Unix seconds. Need state that old note conflicts.
• retry on timeout, network error, 408, 425, 429, and 5xx. Do not retry other 4xx. Schedule roughly 1m, 5m, 30m, 2h, 12h. Five retries after initial try.
• receiver has 10 seconds to return any 2xx. Response body ignored.
• duplicates possible. Delivery order usually follows creation but concurrent retries mean it is not guaranteed.
• secret rotation: two secrets valid for 24 hours; UI labels current/previous.
• replay UI can resend an event for 7 days and uses same event id.
• payload max 512 KiB. User-Agent Orbit-Hooks/2.
• uncertain: are redirects followed? Security thinks no, implementation owner has not confirmed.
• examples should warn against logging secrets or full sensitive payloads.

Task 05 — Technical writing: webhook delivery guide

Turn SOURCE_NOTES.md into WEBHOOKS.md, a developer guide for customers integrating with the service. Target 700–1,100 words.

The guide must include a minimal verification example, delivery and retry semantics, ordering/idempotency guidance, key rotation, operational advice, and a troubleshooting table. Clearly distinguish guarantees from recommendations. Resolve apparent contradictions conservatively and call out anything that still requires product confirmation instead of inventing behavior.

Write RESPONSE.md with your editorial choices and unresolved questions. Work only in this directory.

Receiving Orbit webhooks

Orbit sends JSON events to your receiver using HTTP POST. Build the receiver to authenticate each request, durably accept work, and process duplicates safely. Contract identifies documented guarantees or behavior; Recommendation identifies receiver design choices. Product confirmation marks details that remain unresolved.

Request format and verification

Contract: Requests include X-Orbit-Event (event ID), X-Orbit-Type (event type), X-Orbit-Timestamp (Unix seconds), and X-Orbit-Signature (v1=<hex>). Payloads are at most 512 KiB. The User-Agent is Orbit-Hooks/2; it is not an authentication mechanism.

The current implementation computes HMAC-SHA-256 over:

timestamp_header_bytes + b"." + raw_request_body_bytes

Preserve the body exactly as received. Parsing JSON and serializing it again can change whitespace, key order, or encoding and invalidate the signature. Compare signatures in constant time.

Older documentation says to sign parsed JSON; another abbreviated note mentions only raw bytes. Both conflict with the explicit current implementation formula above. Follow that formula; product confirmation is required to establish it as the final published signing contract.

This minimal Python 3.9+ example uses only the standard library. Pass the unchanged body, the two header values, and securely loaded secret bytes. During rotation, pass both current and previous keys.

import hashlib
import hmac
import re

def verify(raw_body: bytes, timestamp: str, signature: str,
           keys: tuple[bytes, ...]) -> bool:
    if not re.fullmatch(r"[0-9]+", timestamp):
        return False
    match = re.fullmatch(r"v1=([0-9a-fA-F]{64})", signature)
    if match is None:
        return False
    supplied = bytes.fromhex(match.group(1))
    message = timestamp.encode("ascii") + b"." + raw_body
    valid = False
    for key in keys:
        expected = hmac.new(key, message, hashlib.sha256).digest()
        valid |= hmac.compare_digest(expected, supplied)
    return valid

Recommendation: Verify before parsing or enqueueing. Reject malformed headers and failed signatures. The example authenticates the signed bytes but does not enforce timestamp freshness. Confirm how to convert the displayed secret into key bytes; do not assume it is hex or base64. The formula does not cover the event ID or type headers, so do not assume those headers are independently authenticated.

For replay protection, consider a configurable freshness window, such as five minutes, with synchronized clocks. Product confirmation: Do retries and manual replays receive fresh timestamps and signatures? Establish this before enabling strict freshness checks, which could otherwise reject legitimate deliveries.

Delivery and retries

Contract: Your receiver has 10 seconds to return any 2xx response. Orbit ignores the response body. A timeout, network error, HTTP 408, 425, 429, or 5xx triggers retry. Other 4xx responses are not retried.

There are five retries after the initial attempt: at most six attempts in the automatic sequence. Listed retry timings are roughly one minute, five minutes, 30 minutes, two hours, and 12 hours. These are approximate, not scheduling guarantees. Product confirmation: The notes do not establish whether these timings are successive delays or offsets from the initial attempt, or whether Retry-After affects them. Do not derive an exact exhaustion deadline.

Recommendation: Return 2xx only after persisting the event or durably enqueueing it. Complete business processing asynchronously. Return a retryable status when durable acceptance fails or the receiver is temporarily overloaded. Acknowledge an already accepted duplicate with 2xx. A lost acknowledgment can cause another attempt even when your first attempt succeeded locally.

Ordering, idempotency, and replay

Contract: Duplicates are possible. Delivery usually follows event creation, but concurrent retries mean order is not guaranteed. There is no exactly-once processing guarantee. The replay UI can resend an event for seven days and keeps the same event ID.

Recommendation: Use X-Orbit-Event as the deduplication identifier. Make the deduplication record and corresponding state change atomic, or use a durable inbox with unique IDs and idempotent workers. A check-then-write sequence without concurrency protection can process simultaneous duplicates twice. Ensure downstream side effects also tolerate retries.

Retain deduplication records through the seven-day replay period and allow additional margin for delayed processing. The notes do not define the replay period's starting point or event-ID uniqueness scope; confirm these before choosing a retention boundary or a cross-account deduplication key. Avoid assuming arrival order reflects current state; reconcile against authoritative state when available.

Secret rotation and operations

Contract: A secret is shown once. During rotation, two secrets are valid for 24 hours; the UI labels them current and previous.

Recommendation: Store secrets in a secret manager. Deploy verification with both keys during the overlap, monitor acceptance with the current key, and retire the previous key when its validity ends. Do not infer a rotation start time or which key signs outbound requests; confirm the overlap anchor and signing-key transition with product.

Monitor response latency against the 10-second deadline, retryable failures, signature failures, duplicate rates, and queue backlog. Record event IDs, status codes, and timing for diagnosis. Never log secrets or full sensitive payloads. Use bounded request buffering for the 512 KiB limit. Test rotation, concurrent duplicates, slow responses, and durable queue failures before rollout.

Troubleshooting

Symptom	Check and action
Signature mismatch	Preserve raw bytes; use timestamp plus dot plus body; check key bytes and rotation overlap.
Legitimate event rejected as stale	Check clock skew and freshness policy; confirm retry/replay timestamp behavior.
Duplicate side effects	Make deduplication atomic and downstream actions idempotent.
Older event arrives later	Ordering is not guaranteed; reconcile state instead of trusting arrival order.
Repeated attempts	Check timeouts, retryable responses, queue availability, and acknowledgment latency.
No retry after a client error	Other 4xx responses are terminal for automatic retries; fix the receiver and use replay if eligible.
Endpoint redirects	Redirect following is unconfirmed. Security expects no following; configure a directly reachable endpoint.

Editorial choices and unresolved questions

Editorial choices

• Produced WEBHOOKS.md as a customer-facing integration guide using only SOURCE_NOTES.md. No network research or undocumented product behavior was added.
• Separated documented behavior, receiver recommendations, and items requiring product confirmation. In particular, approximate retry timings, usual ordering, and finite retries are not presented as timing, ordering, or eventual-delivery guarantees.
• Resolved the signing contradiction in favor of the explicit current implementation: timestamp text, a literal dot, and the raw body. Called out both the older parsed-JSON instruction and the incomplete raw-body-only description instead of silently reconciling them.
• Used a small standard-library Python verifier with strict timestamp/signature syntax, constant-time digest comparison, and support for both rotation keys. It checks every supplied key and returns false for an empty key set. Framework-specific body access, secret loading, and header validation remain integration responsibilities.
• Did not invent a timestamp tolerance. The example explicitly does not provide freshness protection, because retry/replay timestamp generation is unspecified. Called out that the documented signature does not cover the event ID or type headers.
• Described five retries after the first attempt as six attempts within one automatic sequence. Kept manual replay separate and preserved the approximate schedule without choosing an undocumented interpretation of its timing.
• Connected acknowledgment to durable acceptance and idempotency to persistent, coordinated processing. Explained that replay retains the event ID and should not duplicate completed business effects.
• Treated a directly reachable endpoint as a recommendation while leaving redirect behavior unresolved. Included payload limits, key storage and rollout, safe logging, monitoring, recovery, and a troubleshooting table.

Questions for product and implementation owners

1. Authoritative signing contract: Can the current timestamp-plus-dot-plus-raw-body format be formally confirmed and the stale parsed-JSON documentation removed? How is the displayed secret converted to key bytes? Can the service provide an official test vector?
2. Timestamp and replay protection: Is the timestamp created per attempt, per event, or per manual replay? What age and clock skew should receivers accept? How should a freshness policy accommodate legitimate retries and seven-day replays?
3. Header integrity and parsing: How are event ID and event type authenticated or bound to signed content? Are duplicate header fields or multiple signature values possible, and what parsing rules apply?
4. Retry timing: Are the listed times delays between attempts or offsets from the first attempt? Is there jitter, and does Retry-After affect 429 or other responses? What happens after exhaustion, and how is that outcome exposed to customers?
5. Redirects: Are any 3xx responses followed or retried? Security's expectation is not sufficient to document implementation behavior as a guarantee.
6. Rotation: What starts the 24-hour overlap, when does outbound signing switch keys, and which key signs retries or replays of older events? What happens if another rotation is initiated during the overlap?
7. Event identity and recovery windows: What is the event ID uniqueness scope? When does the seven-day replay window start, can replay trigger another automatic retry sequence, and what is the maximum time an in-flight delivery can arrive after replay eligibility ends? These answers determine safe deduplication retention.

These uncertainties are documented rather than blocking completion of the requested writing. No payload schema, ordering metadata, recovery API, delivery SLA, or other unsupported capability is assumed.

Validation

The guide was checked against each supplied note and the requested coverage. It contains 1,029 whitespace-delimited words including code, or 965 excluding code, within the 700–1,100-word target under either count. The verification example passed 23 local checks covering valid signatures, body and timestamp changes, malformed inputs, empty and rotated key sets, and rejection of raw-body-only signing. Fixture digests were constructed independently of hmac.new; the HMAC implementation also passed RFC 4231 test case 1 using its known expected digest, with no network access. This validates the example's mechanics; it does not replace an official Orbit signing test vector or resolve the product questions above.

Raw webhook notes

• POST JSON. Event id in X-Orbit-Event; event type X-Orbit-Type.
• signature header X-Orbit-Signature: v1=<hex> using HMAC SHA-256 over raw bytes. Secret shown once. Comparison constant-time.
• docs from old system say sign parsed JSON; this is probably stale. Current implementation signs timestamp + dot + raw body. Timestamp header is X-Orbit-Timestamp Unix seconds. Need state that old note conflicts.
• retry on timeout, network error, 408, 425, 429, and 5xx. Do not retry other 4xx. Schedule roughly 1m, 5m, 30m, 2h, 12h. Five retries after initial try.
• receiver has 10 seconds to return any 2xx. Response body ignored.
• duplicates possible. Delivery order usually follows creation but concurrent retries mean it is not guaranteed.
• secret rotation: two secrets valid for 24 hours; UI labels current/previous.
• replay UI can resend an event for 7 days and uses same event id.
• payload max 512 KiB. User-Agent Orbit-Hooks/2.
• uncertain: are redirects followed? Security thinks no, implementation owner has not confirmed.
• examples should warn against logging secrets or full sensitive payloads.

Task 05 — Technical writing: webhook delivery guide

Turn SOURCE_NOTES.md into WEBHOOKS.md, a developer guide for customers integrating with the service. Target 700–1,100 words.

The guide must include a minimal verification example, delivery and retry semantics, ordering/idempotency guidance, key rotation, operational advice, and a troubleshooting table. Clearly distinguish guarantees from recommendations. Resolve apparent contradictions conservatively and call out anything that still requires product confirmation instead of inventing behavior.

Write RESPONSE.md with your editorial choices and unresolved questions. Work only in this directory.

Receiving Orbit webhooks

Orbit sends event notifications as HTTP POST requests containing JSON. Build your receiver to verify each request, durably accept the event, and process it safely when deliveries repeat or arrive out of order.

Contract and uncertainty: “Documented behavior” below describes the supplied service contract and current implementation. “Recommended” identifies receiver design advice. Items marked “Product confirmation required” are unresolved; do not depend on them as guarantees.

Request format

Documented behavior: Payloads have a maximum size of 512 KiB. Requests use User-Agent: Orbit-Hooks/2 and these headers:

Header	Meaning
X-Orbit-Event	Event ID; also reused by manual replay
X-Orbit-Type	Event type
X-Orbit-Timestamp	Timestamp in Unix seconds
X-Orbit-Signature	HMAC SHA-256 digest, formatted as v1=<hex>

The user agent identifies traffic but does not authenticate it. Configure request limits to accommodate the documented payload size.

Verify before processing

Current implementation: The signed message is the timestamp header value, followed by a literal dot (.), followed by the exact raw request body bytes. Compute HMAC SHA-256 with the webhook secret and compare digests in constant time.

Source conflict: Older documentation says to sign parsed JSON; another note mentions raw bytes without the timestamp prefix. The current implementation description specifies timestamp + "." + raw body, so this guide uses that format. Parsing and reserializing JSON can change the bytes and break verification. Product should confirm the format as the authoritative contract and retire the conflicting guidance.

This minimal Python example uses only the standard library. Supply the unchanged timestamp and signature header values, the raw body, and the exact secret bytes from secure configuration:

import hashlib
import hmac
import re


def verify(raw_body: bytes, timestamp: str, signature: str,
           secrets: tuple[bytes, ...]) -> bool:
    if not re.fullmatch(r"[0-9]+", timestamp):
        return False
    match = re.fullmatch(r"v1=([0-9a-fA-F]{64})", signature)
    if match is None:
        return False

    supplied = bytes.fromhex(match.group(1))
    message = timestamp.encode("ascii") + b"." + raw_body
    valid = False
    for secret in secrets:
        expected = hmac.new(secret, message, hashlib.sha256).digest()
        valid |= hmac.compare_digest(expected, supplied)
    return valid

Recommended: Reject missing required headers before calling this function; reject failed verification before parsing or acting on JSON. Pass the current secret and, during rotation, the previous secret. Keep framework middleware from consuming or transforming the body first. The example accepts one v1 digest; it does not define behavior for duplicate headers or multiple signatures.

The example verifies authenticity, not freshness. Product confirmation required: Whether retries and manual replays receive new timestamps is unspecified, as is an accepted clock-skew window. Agree on a freshness policy before enforcing an age limit that could reject legitimate deliveries. A timestamp alone does not prevent replay, and the documented signed message does not include the event ID or type headers; their authenticated binding needs confirmation.

Acknowledgment and retries

Documented behavior: Your receiver has 10 seconds to return any 2xx response. Orbit ignores the response body. Orbit retries timeouts, network errors, HTTP 408, 425, 429, and 5xx responses. Other 4xx responses are not retried.

There are five retries after the initial attempt: at most six attempts in that automatic retry sequence. The listed retry schedule is approximately 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. These are approximate timings, not deadlines. Product confirmation required: The notes do not say whether those values are delays between attempts or offsets from the first attempt; no total retry duration is promised here.

Recommended: Verify and durably enqueue the event, then acknowledge within 10 seconds. Process expensive work asynchronously. If durable acceptance fails temporarily, return a retryable status instead of acknowledging work you could lose. An acknowledgment may be lost in transit, so successful processing does not rule out another delivery. Finite retries do not guarantee eventual receipt.

Product confirmation required: Redirect handling is unknown. Security expects redirects not to be followed, but implementation ownership has not confirmed this. Configure a directly reachable final endpoint and avoid depending on 3xx behavior.

Duplicates, ordering, and recovery

Documented behavior: Duplicates are possible. Delivery usually follows creation order, but concurrent retries mean ordering is not guaranteed. The replay UI can resend an event for seven days and preserves its event ID.

Recommended: Use X-Orbit-Event as the deduplication key within your integration. Persist processing state and coordinate deduplication with business updates or use idempotent downstream operations. An in-memory cache or an uncoordinated “check, then write” can allow duplicate effects under concurrency. Acknowledge an already durably accepted duplicate with 2xx.

Retain deduplication records through the seven-day replay window, with additional allowance for in-flight deliveries and your recovery process; the exact retention horizon needs confirmation. Manual replay is a redelivery, not a request to repeat completed business effects. Avoid letting late events blindly overwrite newer state; reconcile against authoritative state when your application has that capability.

Secret rotation and operations

Documented behavior: The secret is shown once. During rotation, two secrets are valid for 24 hours, labeled current and previous in the UI.

Recommended: Store secrets securely when revealed. During the overlap, deploy verification with both keys to every receiver instance. Confirm the rollout before retiring the previous key after the overlap. Product must confirm the precise overlap start and signing-key switch behavior.

Monitor acknowledgment latency, response codes, signature failures, duplicate rates, and queue backlog. Log event IDs, attempt outcomes, and timings; do not log secrets or full sensitive payloads. Use the replay UI to recover missed events within its seven-day window while preserving deduplication.

Troubleshooting

Symptom	Check and action
Signature fails	Preserve raw bytes and timestamp text; include the dot; check current/previous keys.
Repeated delivery	Check for timeouts or retryable responses; acknowledge promptly and deduplicate.
Failed request is not retried	Check for a non-retryable 4xx or exhausted attempts; consider eligible replay.
State appears to regress	Check arrival order; prevent stale updates and reconcile state.
Failure after rotation	Check all receiver instances have the current secret and overlap has not expired.
Redirected endpoint misses events	Use the final URL directly; redirect handling remains unconfirmed.

Task 05 response: editorial choices and open questions

Deliverables

• WEBHOOKS.md: 1,076 words by wc -w (about 1,025 excluding table pipes; about 795 prose only, excluding the code block and table rows). Sections: request format, verification with a minimal Python example, delivery/timeout/retry semantics, ordering and idempotency, secret rotation, operating a receiver, a troubleshooting table, and an "Unconfirmed" list.
• RESPONSE.md: this file.

The Python example was extracted from the guide and run against a small self-test (valid signature accepted; previous secret accepted during rotation; wrong secret, modified body, stale timestamp and malformed header rejected). The test script lives in the session scratchpad, not in this directory.

Editorial choices

1. Three-way labelling. Every section is tagged Guarantee, Recommendation or Unconfirmed, with the three terms defined once at the top. Guarantees are limited to behaviour the notes state as fact about the service. Everything about how the receiver should behave is a recommendation, even when strongly advised. The notes list "comparison constant-time" as a fact, but it is receiver-side behaviour the service cannot enforce, so it appears as a recommendation.

2. Signature scheme: current implementation only, no fallback. The notes say older docs describe signing the parsed JSON and that this is "probably stale", while the current implementation signs timestamp + "." + raw body. I documented only the current scheme, described the old one as "believed stale", and listed it under Unconfirmed. I deliberately did not suggest "try the old scheme if verification fails": a receiver that accepts two schemes is weaker, and a stale scheme should be retired rather than kept alive in customer code. I read "HMAC over raw bytes" and "timestamp + dot + raw body" as consistent: the raw bytes are the body portion of the signed message.

3. Timestamp tolerance: included as a recommendation, with a caveat. The timestamp exists to bound replay attacks, so the example enforces a 300-second tolerance. The notes do not say whether a manual replay (up to 7 days later) carries a fresh timestamp; if it reuses the original, a tolerance check rejects replays. I kept the check as the secure default and flagged the caveat in the example comment, the troubleshooting table and the Unconfirmed list, with "widen the tolerance while replaying" as the interim workaround.

4. Rotation procedure derived from "shown once". Because a new secret is visible only after it is generated, the receiver cannot pre-load it. The safe order is generate, add, deploy, confirm, remove the old secret within 24 hours. Verifying against a list of secrets works whether the sender signs with the new secret only, the old one until switch-over, or both; which of these it actually does is unconfirmed. I advised replaying any deliveries rejected in the generate-to-deploy gap.

5. 401 for failed verification. Non-listed 4xx responses are not retried. A bad signature will not fix itself on retry, so a final status is correct, and replay covers the rotation-gap case. I rejected the alternative of returning 5xx to force retries because it would mask misconfiguration and burn the retry budget.

6. Retry schedule wording. "Roughly 1m, 5m, 30m, 2h, 12h" could mean gaps between attempts (last retry about 14.6 hours after the first attempt) or offsets from the first attempt (about 12 hours). I wrote "expect the last retry 12–15 hours after the first attempt", which holds under either reading, and kept "roughly".

7. 3xx and redirects. 3xx appears in neither the retry list nor the do-not-retry list, and redirect-following is unconfirmed (security believes no). The guide tells customers to use a URL that answers directly, says a 3xx "may count as a failed delivery", and does not state whether it is retried.

8. Deduplication retention of "8 days or more" is derived from the 7-day replay window plus up to roughly 15 hours of retries for a replayed delivery.

9. 413 advice is derived from the 512 KiB maximum plus "other 4xx not retried". Default body-size limits in many frameworks are far below 512 KiB, which would silently turn large events into final failures.

10. Ordering advice ("treat the event as a signal and re-read the resource from your source of truth") is deliberately generic. The notes describe neither a read API nor the payload schema, so I did not invent one.

11. Logging warning appears next to the example (where it will be copied from) and again under operations, covering secrets, signature values and full payloads.

12. Python, standard library only. It is the shortest correct expression of HMAC, constant-time comparison and a multi-secret loop. The example uses the secret's UTF-8 bytes as the HMAC key; that is an assumption (question 2 below).

13. Left out for lack of source material: payload schema, event type catalogue, IP allowlist, endpoint pausing after sustained failures, and any signing version other than v1. Nothing was invented to fill these gaps.

Unresolved questions for product and the implementation owner

1. Signed message. Confirm it is exactly the X-Orbit-Timestamp value, a ., and the raw body bytes; confirm the "parsed JSON" description is retired everywhere it appears; confirm the hex digest is lowercase. The guide documents the current implementation.
2. Secret encoding. Is the secret used as its literal UTF-8 bytes, or must it be decoded from hex or base64 before use as the HMAC key? The example assumes UTF-8 bytes.
3. Redirects. Does the sender follow them? Is a 3xx response retried, treated as final, or followed? The guide says not to rely on redirects.
4. Rotation window. During the 24 hours, does each delivery carry one signature (signed with which secret?) or two? If two, what is the separator in X-Orbit-Signature? The guide verifies against both secrets; the example checks a single v1= value and would need to split the header if it can carry several.
5. Replay. Does a replayed event carry a fresh X-Orbit-Timestamp and signature? Does a replay go through the normal retry schedule? Does the 7-day window count from event creation or from the last failed attempt?
6. Retry schedule. Are the delays gaps between attempts or offsets from the first attempt? Is there jitter? Is the schedule a commitment or best effort?
7. Oversize payloads. What happens to an event whose payload would exceed 512 KiB: not generated, truncated, or sent with a reference? The guide states only the maximum.
8. Timeout definition. Is the 10-second budget measured to the first response byte or to the complete response, and is there a separate connect timeout?
9. Not in the notes but customers will ask: does the service pause or disable an endpoint after sustained failures, and is there a source IP range to allowlist?

Raw webhook notes

• POST JSON. Event id in X-Orbit-Event; event type X-Orbit-Type.
• signature header X-Orbit-Signature: v1=<hex> using HMAC SHA-256 over raw bytes. Secret shown once. Comparison constant-time.
• docs from old system say sign parsed JSON; this is probably stale. Current implementation signs timestamp + dot + raw body. Timestamp header is X-Orbit-Timestamp Unix seconds. Need state that old note conflicts.
• retry on timeout, network error, 408, 425, 429, and 5xx. Do not retry other 4xx. Schedule roughly 1m, 5m, 30m, 2h, 12h. Five retries after initial try.
• receiver has 10 seconds to return any 2xx. Response body ignored.
• duplicates possible. Delivery order usually follows creation but concurrent retries mean it is not guaranteed.
• secret rotation: two secrets valid for 24 hours; UI labels current/previous.
• replay UI can resend an event for 7 days and uses same event id.
• payload max 512 KiB. User-Agent Orbit-Hooks/2.
• uncertain: are redirects followed? Security thinks no, implementation owner has not confirmed.
• examples should warn against logging secrets or full sensitive payloads.

Task 05 — Technical writing: webhook delivery guide

Turn SOURCE_NOTES.md into WEBHOOKS.md, a developer guide for customers integrating with the service. Target 700–1,100 words.

The guide must include a minimal verification example, delivery and retry semantics, ordering/idempotency guidance, key rotation, operational advice, and a troubleshooting table. Clearly distinguish guarantees from recommendations. Resolve apparent contradictions conservatively and call out anything that still requires product confirmation instead of inventing behavior.

Write RESPONSE.md with your editorial choices and unresolved questions. Work only in this directory.

Orbit webhooks

Orbit notifies your service of events by sending HTTP requests to a URL you configure.

Conventions. Guarantee marks service behaviour you can rely on. Recommendation marks our advice for your receiver. Unconfirmed marks behaviour awaiting product confirmation; do not build on it.

Request format

Guarantee. Every delivery is an HTTP POST with a JSON body of at most 512 KiB and the User-Agent Orbit-Hooks/2. Each request carries:

Header	Meaning
X-Orbit-Event	Unique event id; identical across retries and replays.
X-Orbit-Type	Event type.
X-Orbit-Timestamp	Unix time in seconds when the request was signed.
X-Orbit-Signature	v1=<hex>: HMAC-SHA-256 of the signed message, using your endpoint secret.

Verifying signatures

Guarantee. The signed message is the X-Orbit-Timestamp value, a literal ., and the raw request body bytes exactly as received. Verify before your framework parses or re-serialises the body; any change to whitespace or key order breaks verification. (Older documentation described signing the parsed JSON. That description is believed stale; see Unconfirmed.)

Recommendation. Compare digests in constant time, accept either the current or the previous secret (see Rotating secrets), and reject stale timestamps to limit replay attacks.

import hashlib, hmac, time

TOLERANCE_SECONDS = 300  # recommendation; see Unconfirmed

def verify(headers, raw_body: bytes, secrets: list[str]) -> bool:
    ts = headers["X-Orbit-Timestamp"]
    sig = headers["X-Orbit-Signature"]
    if not sig.startswith("v1=") or abs(time.time() - int(ts)) > TOLERANCE_SECONDS:
        return False
    message = ts.encode() + b"." + raw_body
    for secret in secrets:  # [current, previous] during rotation
        expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
        if hmac.compare_digest(expected, sig[3:]):
            return True
    return False

Reject failures with 401; it is not retried, which is right for a bad signature. If you rejected genuine deliveries (for example during a rotation gap), use replay. Never log secrets, signatures or full payloads.

Delivery, timeouts and retries

Guarantee. Your endpoint has 10 seconds to return any 2xx status; the response body is ignored. A delivery is retried after a connection error, a timeout, or a 408, 425, 429 or 5xx response. Any other 4xx is final and is not retried. Up to five retries follow the initial attempt, with roughly 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours of backoff; expect the last retry 12–15 hours after the first attempt.

After the last retry or a final 4xx, the event is not delivered again automatically; you can resend it from the replay UI for 7 days, with the same event id.

Recommendation. Return 2xx as soon as the event is durably queued, then process it asynchronously; keep slow work out of the 10-second window. Return 5xx (or 429 when overloaded) to request a retry, and a final 4xx only for requests you can never process.

Ordering and idempotency

Guarantee. You may receive the same event more than once; retries, replays and concurrent delivery all produce duplicates. Deliveries usually arrive in creation order, but this is not guaranteed; a retried older event can arrive after a newer one.

Recommendation.

• Treat X-Orbit-Event as the idempotency key. Claim the id atomically before acting (release it if processing fails), and skip ids you have already seen.
• Keep those records for at least the 7-day replay window plus the retry window, so 8 days or more.
• Do not infer state from event order; where current state matters, treat the event as a signal and re-read the resource from your source of truth.
• A replay is an intentional duplicate: to reprocess an event, clear your record for its id first, or deduplication will drop it.

Rotating secrets

Guarantee. The endpoint secret is shown once, when created. After you rotate, the previous and current secrets are both valid for 24 hours (the UI labels them current and previous); after that, only the current secret is valid.

Recommendation.

1. Store the secret in a secrets manager when it is shown; it cannot be retrieved later.
2. Verify against a list of secrets, as in the example.
3. Rotate in the UI, add the new secret to the list immediately, and deploy.
4. Once deliveries verify against the new secret, remove the old one, within 24 hours.
5. Replay any deliveries rejected between rotation and deploy.

Rotate immediately if a secret may have been exposed, for example in logs.

Operating a receiver

Recommendation.

• Use an HTTPS URL that answers directly. Do not rely on redirects (see Unconfirmed).
• Accept request bodies of at least 512 KiB. A 413 from your server is a final 4xx and will not be retried.
• Read the raw body before your framework parses it, and verify before any other processing.
• Log event id, type and outcome only; payloads may contain personal or sensitive data.
• Alert on rising failure or duplicate rates, and check the replay UI for failed deliveries; replay is available for only 7 days.

Troubleshooting

Symptom	Likely cause	Fix
Signature never verifies	Body parsed or re-serialised before hashing; wrong secret	Hash the raw bytes; check the current secret in the UI
Verification fails after rotation	Old secret removed early, or new one not deployed	Add the current secret; replay rejected events
Deliveries fail with no retries	Your endpoint returned a final 4xx (401, 404, 413)	Fix the cause; use replay
Deliveries time out	Handler exceeds 10 seconds	Queue, then return 2xx
Same event arrives twice	Retry or replay; expected	Deduplicate on the event id
Events out of order	Expected	Do not depend on order
Nothing arrives	URL wrong, redirecting, or blocked	Use the final HTTPS URL; allow Orbit-Hooks/2
Replays rejected	Your timestamp tolerance (see Unconfirmed)	Widen the tolerance while replaying

Unconfirmed

These await product confirmation; the guide takes the conservative reading of each.

• Signature input. Older documentation says the parsed JSON is signed; the current implementation signs timestamp.rawbody. This guide documents the current implementation.
• Redirects. Believed not to be followed. Use a URL that responds directly; a 3xx may count as a failed delivery.
• Rotation window. Whether deliveries during the 24-hour window carry one signature or two. Verifying against both secrets works either way.
• Replay timestamps. Whether a replay carries a fresh X-Orbit-Timestamp. If not, a timestamp tolerance rejects replays.

Editorial choices and open questions

Editorial choices

• Treated the current implementation note as authoritative for signature verification: HMAC-SHA-256 covers X-Orbit-Timestamp, a literal period, and the raw body bytes. Explicitly identified the older parsed-JSON instruction as stale because it contradicts that implementation note.
• Separated documented behavior (“Guarantee”) from integration guidance (“Recommendation”), particularly around fast acknowledgment, durable queuing, idempotency, logging, and key handling.
• Interpreted “five retries after initial try” plus the five listed intervals as up to six total delivery attempts, and retained “roughly” because the schedule is approximate.
• Described X-Orbit-Event as a deduplication key while noting that UI replay retains the same ID. This makes the operational consequence visible without implying that a replay creates a distinct event.
• Included a Node.js/Express verification example that preserves the raw request body and compares equal-length digest buffers with a timing-safe function. It demonstrates signature verification without inventing timestamp expiry validation.
• Called out that the documented HMAC does not include the event ID or type headers, so their authentication status needs product confirmation; the guide limits their use to routing and duplicate suppression until clarified.
• Avoided claiming that Orbit follows redirects, retries 3xx, has a particular timeout retry cadence, or provides payload sequence fields.

Product questions to resolve

1. Does Orbit follow endpoint redirects? The notes explicitly say this is unconfirmed. Until answered, integrations should configure the final URL directly.
2. Is there an expected timestamp freshness/replay window, and is the timestamp generated per event or per delivery attempt? The timestamp is signed, but no validation window or regeneration rule is documented.
3. What happens for a 3xx response? Retry rules list certain status codes and say not to retry other 4xx, leaving 3xx unspecified.
4. Is X-Orbit-Event globally unique, and does manual replay intentionally preserve the ID so receiver-side deduplication suppresses it? The seven-day replay window and stable replay ID are documented, but uniqueness scope and intended reprocessing behavior are not.
5. Are the listed retry intervals measured from the preceding attempt, and does retrying stop immediately after the fifth retry fails? The notes give approximate intervals and a retry count, but not exact clock semantics or post-exhaustion status visibility.
6. Should X-Orbit-Event and X-Orbit-Type be included in the authenticated signing input, or are they intentionally unsigned? The documented formula signs the timestamp and raw body only.

Raw webhook notes

• POST JSON. Event id in X-Orbit-Event; event type X-Orbit-Type.
• signature header X-Orbit-Signature: v1=<hex> using HMAC SHA-256 over raw bytes. Secret shown once. Comparison constant-time.
• docs from old system say sign parsed JSON; this is probably stale. Current implementation signs timestamp + dot + raw body. Timestamp header is X-Orbit-Timestamp Unix seconds. Need state that old note conflicts.
• retry on timeout, network error, 408, 425, 429, and 5xx. Do not retry other 4xx. Schedule roughly 1m, 5m, 30m, 2h, 12h. Five retries after initial try.
• receiver has 10 seconds to return any 2xx. Response body ignored.
• duplicates possible. Delivery order usually follows creation but concurrent retries mean it is not guaranteed.
• secret rotation: two secrets valid for 24 hours; UI labels current/previous.
• replay UI can resend an event for 7 days and uses same event id.
• payload max 512 KiB. User-Agent Orbit-Hooks/2.
• uncertain: are redirects followed? Security thinks no, implementation owner has not confirmed.
• examples should warn against logging secrets or full sensitive payloads.

Task 05 — Technical writing: webhook delivery guide

Turn SOURCE_NOTES.md into WEBHOOKS.md, a developer guide for customers integrating with the service. Target 700–1,100 words.

The guide must include a minimal verification example, delivery and retry semantics, ordering/idempotency guidance, key rotation, operational advice, and a troubleshooting table. Clearly distinguish guarantees from recommendations. Resolve apparent contradictions conservatively and call out anything that still requires product confirmation instead of inventing behavior.

Write RESPONSE.md with your editorial choices and unresolved questions. Work only in this directory.

Webhook delivery and verification

Orbit sends event notifications as JSON POST requests. Each request includes X-Orbit-Event (event ID), X-Orbit-Type (event type), X-Orbit-Timestamp (Unix seconds), and X-Orbit-Signature. The request body is limited to 512 KiB, and the sender identifies itself with the Orbit-Hooks/2 User-Agent.

This guide labels documented service behavior as Guarantee and implementation advice as Recommendation. “Guarantee” reflects the current product notes; where those notes are unclear, the limit is called out.

Verify the signature

Guarantee: The signature is v1=<hex> and uses HMAC-SHA-256 over the timestamp, a period, and the exact raw request-body bytes:

HMAC-SHA-256(secret, timestamp + "." + raw_body)

An older note says to sign parsed JSON. That description conflicts with the current implementation and should be treated as stale. Parsing and re-serializing JSON can change whitespace, escaping, or key order, so verify the original bytes. Compare signatures in constant time. Orbit shows a secret only once; store it in a secret manager or protected environment variable and never log it.

Product confirmation needed: The documented HMAC input includes the timestamp and body, but not the event ID or event type headers. As documented, the signature does not bind those headers. Use them for routing and duplicate suppression, but do not treat them as authenticated authorization data until Orbit confirms the intended signing contract.

Minimal Node.js/Express example: install the raw-body handler on this route before any JSON parser, and replace the queue call with your durable queue or database operation.

import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

const app = express();
const secret = process.env.ORBIT_WEBHOOK_SECRET;

app.post('/webhooks/orbit', express.raw({
  type: 'application/json', limit: 512 * 1024,
}), async (req, res) => {
  const timestamp = req.get('X-Orbit-Timestamp');
  const signature = req.get('X-Orbit-Signature') ?? '';
  if (!secret || !timestamp || !/^v1=[0-9a-fA-F]{64}$/.test(signature)) {
    return res.sendStatus(400);
  }

  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.`).update(req.body).digest();
  const supplied = Buffer.from(signature.slice(3), 'hex');
  if (supplied.length !== expected.length ||
      !timingSafeEqual(supplied, expected)) return res.sendStatus(401);

  const eventId = req.get('X-Orbit-Event');
  const eventType = req.get('X-Orbit-Type');
  await enqueueDurably({ eventId, eventType, rawBody: req.body });
  return res.sendStatus(204);
});

This example checks the HMAC only. Product confirmation needed: the notes do not define a timestamp freshness window, so do not invent an age limit and reject requests based on one without confirming the policy. The timestamp is part of the signed input; it is not itself proof that a request is recent.

Delivery, retries, and acknowledgments

Guarantee: Orbit considers any 2xx response an acknowledgment, waits at most 10 seconds for it, and ignores the response body. It retries timeouts, network errors, 408, 425, 429, and 5xx responses. Other 4xx responses are not retried. The approximate retry delays are 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. The notes do not say whether each delay is measured from the preceding attempt or from the initial attempt. That is five retries after the initial delivery, or at most six attempts when every attempt needs a retry.

Recommendation: Validate and durably enqueue a verified event, then return 2xx promptly; do slow work asynchronously. Acknowledge only after the event is safely recorded, because Orbit will not use the response body to learn whether your application accepted it. Return a non-2xx when you cannot safely accept it. Do not rely on redirects: the notes do not say whether Orbit follows them, and redirect behavior needs product confirmation. Configure the final HTTPS endpoint directly.

Ordering and idempotency

Guarantee: Duplicate deliveries can occur. Delivery generally follows event creation order, but concurrent retries mean order is not guaranteed. A replay from the UI is available for seven days and uses the same event ID as the original event.

Recommendation: Make processing idempotent. Persist X-Orbit-Event with the processing result and use it to prevent duplicate side effects. Do not use arrival order as event order. If an event type carries an authoritative version or sequence in its payload, apply updates using that value; otherwise reconcile with your source of truth when order matters. Since a manual replay retains the event ID, your deduplication policy may treat it as already processed; decide how operators should recover or reprocess an event. The notes do not specify a global uniqueness scope or a separate replay identifier.

Rotate signing keys

Guarantee: During rotation, the current and previous secrets are both valid for 24 hours; the UI labels them “current” and “previous.”

Recommendation: On rotation, securely store the new current secret and keep the previous secret available during the overlap. If you cannot identify which key signed a request from another header, verify against each active secret using the same constant-time comparison. Remove the previous key after the 24-hour overlap ends and update the secret manager promptly. Never write either key to application logs, tickets, or shell history.

Operate and troubleshoot

Recommendation: Track delivery outcomes, acknowledgment latency, event IDs and types, and processing failures. Keep logs useful but limited: redact credentials and avoid logging full payloads, which may contain sensitive data. Alert on a growing backlog or repeated verification failures. Ensure the endpoint can accept payloads up to 512 KiB and respond within the 10-second acknowledgment window.

Symptom	What to check
Signature verification fails	Capture the raw bytes before JSON middleware; concatenate the timestamp, period, and those bytes; check the active secret(s) and v1= hex header. Do not sign parsed JSON.
The sender reports timeouts or repeats events	Keep synchronous work short; durably enqueue before returning any 2xx, and make downstream effects idempotent by event ID.
Events appear out of order	Retries can race. Do not process by arrival order; use an authoritative payload version if available or reconcile state.
Delivery stops after an error	Check the HTTP status. Only the listed statuses and network/timeout failures are retried; other 4xx responses are not. The automatic schedule has five retries.
Redirected endpoint does not receive events	Point Orbit directly at the final endpoint. Redirect-following behavior is unconfirmed; ask the product team before depending on it.
A large request is rejected	Check that your server and middleware allow bodies up to 512 KiB and preserve the raw bytes for verification.

Editorial notes

WEBHOOKS.md is a customer integration guide built only from SOURCE_NOTES.md. wc -w reports 1087 words, including headings, tables, and the code sample. That sits inside the 700–1,100 target.

How the guide is labeled

Three labels separate contract from advice.

• Guarantee is behavior the notes state as current delivery behavior.
• Recommendation is what a receiver should do under those rules, including constant-time comparison and not logging secrets or sensitive bodies.
• Unconfirmed is a gap. The guide names it and does not fill it.

Contradiction: what is signed

The notes disagree with themselves. Older docs sign parsed, re-serialized JSON. The current implementation signs X-Orbit-Timestamp, one ., and the raw body, with HMAC-SHA256, and sends v1= plus a hex digest.

I treated the current implementation as the contract and the older text as the conflicting, probably stale account the notes already flag. The guide tells readers to sign that byte string and says a parse-and-re-encode check will not match live traffic. I did not document dual acceptance. Nothing says a parsed-JSON signature still verifies, and claiming that it does would paper over the conflict instead of resolving it.

The first note says the MAC is “over raw bytes.” I read that as “do not re-encode,” and the later note as the actual input (timestamp, dot, raw body). Both sentences appear in the guide so a reader does not implement body-only signing.

Other choices

Order. “Usually follows creation” stays as the common case. It is not a guarantee, because the same notes say concurrent retries can reorder deliveries. No per-entity order is promised. The JSON schema is absent, so no payload field is named as a cursor.

Duplicates. The notes say duplicates are possible. I did not upgrade that to a formal at-least-once promise that every event eventually arrives. A non-retryable 4xx, or the end of the five retries, can stop automatic attempts. Receivers must tolerate repeats. They should not assume eventual success.

Retries. “Five retries after the initial try” is six attempts. The five approximate times are attached to those retries. “Roughly” is preserved: the clock is not an SLA. I did not decide whether each number is a gap after the previous attempt or an offset from the first failure.

Ten seconds and “timeout.” The notes list a 10-second budget to return any 2xx, and separately say timeouts are retried. The guide joins them in one explicit sentence (“Read together…”). That join is an editorial reading of two adjacent notes, not a single quoted rule. It is also listed below as something product can still confirm.

Status codes. Retries follow the list given: timeout, network error, 408, 425, 429, and 5xx. Other 4xx codes are not retried. Any 2xx succeeds. Because the body is ignored, a 200 whose JSON reports failure still counts as success. I stated that so a handler does not ack with an error payload.

Rotation. Both the current and previous secrets are valid for 24 hours, and the UI labels them that way. The receiver is told to accept either match. The notes do not say which secret signs during the overlap, so the guide does not pick one. There is no immediate-revoke feature in the notes, so none is described.

Show-once secret. The secret is shown once. “If you lost it, rotate and store the new value” is operational advice inferred from show-once plus the rotation UI. It is not a documented recovery API.

Event id on retry. Replay reuses X-Orbit-Event; that sentence is explicit. The header table also says automatic retries reuse it. That half is an inference: the header is an event id, not a delivery-attempt id, and duplicates are expected. There is no separate attempt id in the notes. Worth a product confirmation.

512 KiB. Written as 524,288 bytes because KiB is 1024 bytes. That is unit conversion, not a new cap. What the producer does above the cap is not described.

HTTPS. Recommended only. The notes never require a URL scheme. Plain HTTP is called out because it would expose bodies, with a pointer to confirm policy.

Redirects. Not resolved. Security’s “do not follow” position is reported as Security’s position. The practical advice is to register a URL that itself returns 2xx, which is safe whether or not redirects are followed.

Example. One Python 3 standard-library function. It encodes the displayed secret as UTF-8 and uses lowercase hexdigest(). The guide says letter case and any binary key format are unspecified and tells the reader to fail closed. I did not add base64 decoding, a secret prefix, extra signature versions, or whitespace trimming. The header format in the notes is v1=<hex> with nothing else.

Left out on purpose

No event-type catalog, JSON schema, ordering field, jitter formula, endpoint auto-disable, customer alert, or dead-letter queue. No Content-Type value. No invented clock-skew window. No claim that replay refreshes X-Orbit-Timestamp. No claim about which rotation secret signs. No 3xx retry class. No multi-value signature header.

Unresolved questions

1. Are redirects followed? Security believes they are not. The implementation owner has not confirmed that. How is a 3xx classified for retry?
2. Is the 10-second receiver budget the same timer as the retryable timeout, or is there a separate connect or read timeout?
3. What clock skew, if any, is allowed for X-Orbit-Timestamp?
4. On a replay inside 7 days, is X-Orbit-Timestamp the original value or a new one?
5. Is the hex digest lowercase, uppercase, or accepted in either case?
6. Is the signing key the exact displayed string (the sample uses UTF-8), or is there a binary or base64 step?
7. During the 24-hour overlap, which secret signs new deliveries, current or previous?
8. Are 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours gaps between attempts or offsets from the first failure? Is there jitter?
9. After the fifth retry fails, does Orbit pause the endpoint, alert, dead-letter the event, or do nothing further?
10. What happens to an event that would exceed 512 KiB?
11. What is the JSON schema, the set of X-Orbit-Type values, and is there an official ordering or version field?
12. Must the endpoint URL be HTTPS?
13. Do automatic retries, not only the replay UI, send the same X-Orbit-Event?

Raw webhook notes

• POST JSON. Event id in X-Orbit-Event; event type X-Orbit-Type.
• signature header X-Orbit-Signature: v1=<hex> using HMAC SHA-256 over raw bytes. Secret shown once. Comparison constant-time.
• docs from old system say sign parsed JSON; this is probably stale. Current implementation signs timestamp + dot + raw body. Timestamp header is X-Orbit-Timestamp Unix seconds. Need state that old note conflicts.
• retry on timeout, network error, 408, 425, 429, and 5xx. Do not retry other 4xx. Schedule roughly 1m, 5m, 30m, 2h, 12h. Five retries after initial try.
• receiver has 10 seconds to return any 2xx. Response body ignored.
• duplicates possible. Delivery order usually follows creation but concurrent retries mean it is not guaranteed.
• secret rotation: two secrets valid for 24 hours; UI labels current/previous.
• replay UI can resend an event for 7 days and uses same event id.
• payload max 512 KiB. User-Agent Orbit-Hooks/2.
• uncertain: are redirects followed? Security thinks no, implementation owner has not confirmed.
• examples should warn against logging secrets or full sensitive payloads.

Task 05 — Technical writing: webhook delivery guide

Turn SOURCE_NOTES.md into WEBHOOKS.md, a developer guide for customers integrating with the service. Target 700–1,100 words.

The guide must include a minimal verification example, delivery and retry semantics, ordering/idempotency guidance, key rotation, operational advice, and a troubleshooting table. Clearly distinguish guarantees from recommendations. Resolve apparent contradictions conservatively and call out anything that still requires product confirmation instead of inventing behavior.

Write RESPONSE.md with your editorial choices and unresolved questions. Work only in this directory.

Orbit webhook delivery

Orbit sends each event as an HTTP POST. Guarantee is current behavior. Recommendation is integrator practice. Unconfirmed points are collected at the end.

Request

Guarantee. The body is JSON and at most 512 KiB (524,288 bytes). User-Agent is Orbit-Hooks/2. Every delivery sets these headers:

Header	Value
X-Orbit-Event	Event id. Retries and manual replays reuse it.
X-Orbit-Type	Event type.
X-Orbit-Timestamp	Unix time in whole seconds, as decimal text.
X-Orbit-Signature	v1= and a hexadecimal HMAC-SHA256.

Recommendation. Keep the raw body for verification, then parse JSON. Allow at least 524,288 bytes at the proxy. The user agent is a log label; the signature authenticates the call.

Signatures

Guarantee. Orbit signs the exact X-Orbit-Timestamp value, one ., and the raw body, using HMAC-SHA256 and the endpoint secret. The header is v1= plus the hex digest.

Older docs signed parsed, re-serialized JSON. That conflicts with the current implementation, and the notes mark it as probably stale. Sign that byte string. A check that parses and re-encodes JSON will not match live traffic.

Recommendation. Compare digests in constant time. The secret is shown once; store it immediately. On failure, log the event id and type, and leave the secret and any sensitive body out of logs.

The sample uses the shown secret as UTF-8 and lowercase hex. Case and binary key format are unspecified, so keep failing closed until Orbit confirms them.

import hmac, hashlib

def verify(secret: str, timestamp: str, raw_body: bytes, signature_header: str) -> bool:
    if not signature_header.startswith("v1="):
        return False
    message = timestamp.encode("utf-8") + b"." + raw_body
    digest = hmac.new(secret.encode("utf-8"), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(digest, signature_header[3:])

Pass the timestamp header and the raw body through unchanged. No skew window is published. The notes also do not say whether a 7-day replay keeps the original X-Orbit-Timestamp. Recommendation: accept a delivery with a valid v1 signature, and add a freshness cutoff only after Orbit publishes one.

Delivery and retries

Guarantee. Orbit waits 10 seconds for the response. Any 2xx succeeds. The body is ignored, so a 200 counts even when its JSON says the handler failed. Orbit retries timeouts, network errors, 408, 425, 429, and any 5xx. Other 4xx codes are not retried. Five retries follow the first attempt. The approximate schedule for those retries is 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours.

Read together, a response after 10 seconds is that timeout. The status rules and the five-retry cap are firm. Timing is not an SLA: the notes never say whether each figure is a gap after the previous attempt or an offset from the first failure.

Recommendation. Store X-Orbit-Event before you return 2xx, including a stored skip of a duplicate, and queue slow work. If the process dies after a side effect, Orbit delivers again, so stay idempotent. Use 408, 425, 429, or 5xx when a later try might succeed. Any other 4xx ends the schedule. The replay UI resends that same event id for 7 days.

Unconfirmed. Security believes redirects are not followed. The implementation owner has not confirmed that, or how a 3xx is retried. Register a URL that returns 2xx directly. Behavior after the fifth retry is also unconfirmed.

Ordering and idempotency

Guarantee. The same event can arrive more than once. Replay within 7 days reuses X-Orbit-Event. Creation order is usual and not guaranteed: concurrent retries can deliver an older event after a newer one.

Recommendation. Record X-Orbit-Event uniquely in the same transaction as the side effect. Return 2xx and stop when that id is already complete. Process a replay whose id never finished. Keep your own sequence if order matters. The JSON schema is not in these notes, so no body field is named as an ordering key.

Key rotation

Guarantee. Current and previous secrets are both valid for 24 hours. The UI labels them that way.

Recommendation. Treat the signature as valid when either secret produces it. Deploy the new secret first, and keep the previous one until the 24 hours end. Which secret signs during the overlap is unconfirmed. Each secret is shown once. If you did not store it, rotate and save the new secret when it is displayed.

Operations

Recommendation. Count proxy time inside the 10 seconds, and use a separate secret per environment. Prefer HTTPS. The notes never require a scheme; confirm policy before using plain HTTP, which exposes bodies. Alert before the long retry tail. In tickets, quote X-Orbit-Event and omit secrets and sensitive payloads.

Troubleshooting

What you see	Likely cause	What to do
Every signature fails	Signed parsed JSON, or dropped timestamp.	Sign timestamp, ., and raw body
Tests pass, production fails	Body or secret changed on the way in	Use original bytes and the shown secret
Failures start at rotation	A still-valid secret is missing	Try current and previous for 24 hours
Same event again	A retry, a replay, or another copy	Dedupe on X-Orbit-Event; return 2xx
Newer event applied first	Overlapping retries	Use your own sequence
One 4xx, then silence	Not 408, 425, or 429	Fix the handler; replay within 7 days
More tries near 1m / 5m / 30m / 2h / 12h	Timeout, network error, 408, 425, 429, or 5xx	Store the id; 2xx within 10 seconds
Replay does nothing	Id already complete	Reprocess only unfinished ids
Redirect target is quiet	Redirects are unconfirmed	Return 2xx on the registered URL
Edge rejects the body	Buffer under 512 KiB	Allow at least 524,288 bytes

Needs product confirmation

• Redirect following, and whether 3xx is retried. Security believes redirects are not followed; implementation has not confirmed it.
• Clock skew, hex case, secret encoding, and whether replay keeps X-Orbit-Timestamp.
• Which secret signs during the 24-hour overlap.
• Whether schedule numbers are gaps or offsets from the first attempt.
• Policy after the fifth retry, and events larger than 512 KiB.
• JSON schema, X-Orbit-Type values, and any ordering field.
• Whether the URL must be HTTPS.

Until those are answered, verify v1 (timestamp, dot, and raw body), return 2xx quickly, dedupe on X-Orbit-Event, and accept both secrets for 24 hours.

RESPONSE.md — editorial choices and unresolved questions

Editorial choices

1. Signature contradiction resolved toward the current implementation. SOURCE_NOTES.md contains three related claims: HMAC SHA-256 "over raw bytes"; legacy docs signing parsed JSON; and the current implementation signing timestamp + "." + raw body. I documented HMAC-SHA256(secret, "<timestamp>.<raw body>") as the guarantee, flagged the legacy parsed-JSON description as stale/conflicting, and did not invent a compatibility path. Product confirmation is requested in the guide.

2. Guarantees vs recommendations labeled explicitly. Every normative statement carries a **Guarantee** or **Recommendation** marker so customers can tell product behavior from operational advice.

3. Retry semantics taken literally. Retry on timeout, network error, 408, 425, 429, 5xx; all other 4xx terminal; five retries after the initial attempt at roughly 1m/5m/30m/2h/12h. The schedule is marked approximate because the notes say "roughly."

4. Success criterion stated tightly. Any 2xx within 10 seconds; response body ignored. The 10-second timeout is presented as what triggers a retry on timeout (interpretation; see questions).

5. Ordering kept weak. "Usually follows creation" is preserved as a soft observation, with an explicit statement that order is not guaranteed and duplicates are possible. Idempotency on X-Orbit-Event is a recommendation, not a claim that the platform deduplicates.

6. Key rotation and replay documented with concrete windows. Two secrets for 24 hours with UI labels current/previous; replay UI for 7 days reusing the same event id. Verification against both secrets during overlap is a recommendation.

7. Redirects left as unknown. Security's "no" is reported as a belief, not a guarantee, because the implementation owner has not confirmed. I invented no behavior and advised against relying on redirects for migration.

8. Operational safety wording from the notes is included as required: examples warn against logging secrets or full sensitive payloads. HTTPS is framed as a recommendation only — the notes never state it is required.

9. Nothing invented beyond the notes. No IP allowlists, content-type rules, signature-scheme version negotiation, or contractual clock-skew windows. Clock-skew rejection appears only as a recommendation whose threshold is left to the customer.

10. Target length and shape. The guide is structured for skimming (request format, verification, retries, ordering, rotation, replay, operations, troubleshooting table, open questions) and kept within the 700–1,100 word band.

Unresolved questions (need product confirmation)

1. Signature input. Is the signed message timestamp + "." + raw body (current implementation) or parsed JSON (legacy docs)? Please confirm and retire the stale documentation.
2. Redirects. Are HTTP redirects followed on delivery? Security believes not; the implementation owner has not confirmed.
3. HTTPS requirement. Must customer endpoints be HTTPS, or is HTTP acceptable? Documented as a recommendation pending confirmation.
4. Retry schedule precision. Are 1m/5m/30m/2h/12h contractual or best-effort? Stated as approximate.
5. 10-second timeout semantics. Is a 2xx arriving after 10 seconds treated as failure (and retried)? Assumed yes via "retry on timeout."
6. Secret scope and labeling. Is the secret shown once per endpoint or per workspace, and how does the current/previous labeling behave with multiple endpoints?

Raw webhook notes

• POST JSON. Event id in X-Orbit-Event; event type X-Orbit-Type.
• signature header X-Orbit-Signature: v1=<hex> using HMAC SHA-256 over raw bytes. Secret shown once. Comparison constant-time.
• docs from old system say sign parsed JSON; this is probably stale. Current implementation signs timestamp + dot + raw body. Timestamp header is X-Orbit-Timestamp Unix seconds. Need state that old note conflicts.
• retry on timeout, network error, 408, 425, 429, and 5xx. Do not retry other 4xx. Schedule roughly 1m, 5m, 30m, 2h, 12h. Five retries after initial try.
• receiver has 10 seconds to return any 2xx. Response body ignored.
• duplicates possible. Delivery order usually follows creation but concurrent retries mean it is not guaranteed.
• secret rotation: two secrets valid for 24 hours; UI labels current/previous.
• replay UI can resend an event for 7 days and uses same event id.
• payload max 512 KiB. User-Agent Orbit-Hooks/2.
• uncertain: are redirects followed? Security thinks no, implementation owner has not confirmed.
• examples should warn against logging secrets or full sensitive payloads.

Task 05 — Technical writing: webhook delivery guide

Turn SOURCE_NOTES.md into WEBHOOKS.md, a developer guide for customers integrating with the service. Target 700–1,100 words.

The guide must include a minimal verification example, delivery and retry semantics, ordering/idempotency guidance, key rotation, operational advice, and a troubleshooting table. Clearly distinguish guarantees from recommendations. Resolve apparent contradictions conservatively and call out anything that still requires product confirmation instead of inventing behavior.

Write RESPONSE.md with your editorial choices and unresolved questions. Work only in this directory.

Orbit Webhooks

Orbit delivers events to your endpoint as HTTP POST requests with JSON bodies. Verify the signature before you trust a payload. This guide covers request format, verification, delivery semantics, and production operations.

Throughout, Guarantee marks documented product behavior; Recommendation marks operational advice you may choose to ignore.

Request format

Each delivery is an HTTP POST with a JSON body of at most 512 KiB and User-Agent: Orbit-Hooks/2.

Header	Value
X-Orbit-Event	Event id — stable across retries and replays
X-Orbit-Type	Event type
X-Orbit-Timestamp	Unix time in seconds (signature input)
X-Orbit-Signature	v1=<hex> HMAC SHA-256 signature

Recommendation. Acknowledge event types you do not recognize with 2xx and no-op, so new types roll out without breaking you.

Signature verification

Guarantee (current implementation). X-Orbit-Signature is HMAC-SHA256 keyed by your signing secret over the ASCII bytes of "<X-Orbit-Timestamp>.<raw request body>". Note the literal . separator and that the body is the exact bytes received — not re-serialized JSON. The digest is lowercase hex, prefixed with v1=.

Conflict — requires product confirmation. Older documentation states that the signature covers parsed JSON. That description conflicts with the current implementation and is likely stale. This guide follows the current implementation (timestamp + "." + raw body). Do not implement a JSON-re-serialization scheme; see Open questions.

Guarantee. The signing secret is shown once at creation. Store it in a secret manager immediately; it cannot be re-displayed.

Minimal verification example (Python 3):

import hashlib
import hmac

def verify(secret: str, timestamp: str, body: bytes, signature_header: str) -> bool:
    message = f"{timestamp}.".encode("ascii") + body
    digest = hmac.new(secret.encode("ascii"), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"v1={digest}", signature_header)

Recommendation. Always compare in constant time (as above). Reject requests whose X-Orbit-Timestamp is more than a few minutes away from your clock to bound replay risk — the acceptable skew is your policy, not a product setting. Never log signing secrets or full sensitive payloads; log event ids and types only.

Delivery and retries

Guarantee. A delivery succeeds only if your endpoint returns any 2xx within 10 seconds. Response bodies are ignored.

Guarantee. Orbit retries on timeout, network errors, and HTTP 408, 425, 429, and 5xx. Any other 4xx is terminal and is not retried.

Guarantee. After the initial attempt there are five retries, scheduled roughly at 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. Timing is approximate.

Recommendation. Return 2xx as soon as the event is durably queued and do heavy work asynchronously, so you stay inside the 10-second window. Use 5xx or 429 for transient failures you want retried. Return a non-retryable 4xx (for example 400) only when you want Orbit to stop.

Ordering and idempotency

Guarantee. Duplicates are possible. A retry can race an earlier slow success, and the replay UI (below) intentionally resends events.

Guarantee. Delivery order is not guaranteed. Deliveries usually follow event creation order, but concurrent retries can reorder them.

Recommendation. Make handlers idempotent keyed on X-Orbit-Event: persist processed ids and no-op on repeats. Do not assume event N is processed before event N+1.

Key rotation

Guarantee. During rotation, two secrets are valid for 24 hours. The UI labels them current and previous.

Recommendation. While rotating, accept signatures from either secret; drop the previous secret when the 24-hour window closes.

Replaying events

Guarantee. For 7 days after an event, the replay UI can resend it. Replays reuse the original X-Orbit-Event id.

Recommendation. Rely on idempotent handlers so replays are free.

Operational advice

Recommendation. Expose a publicly reachable HTTPS endpoint. Secrets and payloads are sensitive.

Recommendation. Keep verification and acknowledgment fast; defer business logic past the 2xx.

Recommendation. On an invalid signature, do not process the request. Return a non-retryable 4xx and log only metadata (event id, type, timestamp) — never the secret or the full body.

Recommendation. Size handlers for 512 KiB request bodies.

Unconfirmed. Whether Orbit follows HTTP redirects on delivery is unknown. Security believes redirects are not followed; the implementation owner has not confirmed. Do not use redirects to migrate an endpoint — update the configured URL instead.

Troubleshooting

Symptom	Likely cause	What to do
No deliveries arriving	Endpoint unreachable or wrong configured URL	Confirm public reachability; check Orbit's delivery log
Every signature check fails	Signed re-serialized JSON, or omitted the timestamp. prefix	HMAC the exact raw bytes of "<timestamp>.<raw body>"
Intermittent signature failures	Clock skew, or wrong secret during rotation	Check X-Orbit-Timestamp; try both secrets inside the 24-hour overlap
Duplicate side effects	Retries or replays hitting a non-idempotent handler	Dedupe on X-Orbit-Event
Events processed out of order	Concurrent retries	Remove ordering assumptions
Retries stopped unexpectedly	Endpoint returned a non-retryable 4xx	Return 2xx once accepted; use 5xx/429 for transient failures
Event undelivered after ~12 hours	All five retries exhausted	Replay from the UI within 7 days
Handler truncated the request	Body larger than expected	Accept up to 512 KiB

Open questions (require product confirmation)

1. Signature input. Legacy docs say parsed JSON; current notes say timestamp + "." + raw body. This guide documents the current implementation. Please confirm and retire the stale description.
2. Redirects. Unconfirmed (security: not followed; implementation owner: not confirmed). Documented as unknown; do not depend on redirects.
3. Endpoint scheme. Whether HTTPS is required or merely recommended is not stated. Treated here as a recommendation.
4. Retry schedule precision. Delays are described as "roughly" 1m/5m/30m/ 2h/12h. Confirm whether those are contractual or best-effort.

Response: editorial choices and open questions

Editorial choices

• Guarantee vs. recommendation labels: Every behavior paragraph is prefixed with bold Guarantee (service commits to it per the notes) or Recommendation (receiver-side advice the service does not enforce). This keeps the required distinction visible without a separate legend the reader could miss.
• Signature contradiction resolved toward the current implementation: The notes say old docs describe signing parsed JSON but the current implementation signs timestamp + "." + raw body. I documented only the current form as the guarantee, marked the old note stale in Section 1, and warned to verify raw bytes before parsing (re-serialization breaks signatures).
• Conservative retry wording: The schedule is stated as nominal and approximate ("approximately ... not a timing guarantee") because the notes say "roughly". The retryable set (timeout, network error, 408, 425, 429, 5xx) and the non-retry of other 4xx are stated as guarantees, with receiver guidance on which status to return.
• Ordering stated as no guarantee: "Usually in creation order" is explicitly downgraded to background context; the guarantee is that order is not guaranteed, with idempotency keyed on X-Orbit-Event as the recommendation.
• No invented timestamp tolerance: The notes give no clock-skew window, so the 5-minute freshness check is framed as an example receiver policy, not a service requirement.
• Rotation as try-current-then-previous: The notes only say two secrets are valid for 24 hours with UI labels. The fallback-then-remove pattern is presented as a recommendation, not a service behavior.
• Replay and duplicates unified: The 7-day replay with the same event ID is placed under ordering/idempotency so readers treat replays as expected duplicates rather than new events.
• Logging warning kept in the code section: Placed next to the verification example where a developer is most likely to add debug logging, rather than buried in operations.
• Redirects not documented as behavior: Left as an explicit unresolved item in its own section and in troubleshooting, with the conservative advice to use a final URL.

Unresolved questions needing product confirmation

1. Redirects: Are any 3xx responses followed (which codes, how many hops, method/body preserved)? Security believes no, but the implementation owner has not confirmed. Blocks firm guidance.
2. Timestamp validation: Is there a sender-side or required receiver-side clock-skew window? Should receivers reject old timestamps, and at what age?
3. Retry details: What counts as "timeout" vs. "network error" (connect vs. read, DNS failure, TLS failure)? Is there jitter on the nominal 1m/5m/30m/2h/12h schedule, and does the schedule restart after a replay?
4. Signature versioning: Is v1 the only version receivers will see? How should unknown versions be handled, and will new versions overlap like secrets during migration?
5. Oversize payloads: What happens above 512 KiB — never sent, truncated, or delivered with an error signal? Should receivers pre-reject by Content-Length?
6. Replay signing secret: Is a replayed event re-signed with the current secret or the secret active at original delivery? This affects how long old secrets must be retained.

Raw webhook notes

• POST JSON. Event id in X-Orbit-Event; event type X-Orbit-Type.
• signature header X-Orbit-Signature: v1=<hex> using HMAC SHA-256 over raw bytes. Secret shown once. Comparison constant-time.
• docs from old system say sign parsed JSON; this is probably stale. Current implementation signs timestamp + dot + raw body. Timestamp header is X-Orbit-Timestamp Unix seconds. Need state that old note conflicts.
• retry on timeout, network error, 408, 425, 429, and 5xx. Do not retry other 4xx. Schedule roughly 1m, 5m, 30m, 2h, 12h. Five retries after initial try.
• receiver has 10 seconds to return any 2xx. Response body ignored.
• duplicates possible. Delivery order usually follows creation but concurrent retries mean it is not guaranteed.
• secret rotation: two secrets valid for 24 hours; UI labels current/previous.
• replay UI can resend an event for 7 days and uses same event id.
• payload max 512 KiB. User-Agent Orbit-Hooks/2.
• uncertain: are redirects followed? Security thinks no, implementation owner has not confirmed.
• examples should warn against logging secrets or full sensitive payloads.

Task 05 — Technical writing: webhook delivery guide

Turn SOURCE_NOTES.md into WEBHOOKS.md, a developer guide for customers integrating with the service. Target 700–1,100 words.

The guide must include a minimal verification example, delivery and retry semantics, ordering/idempotency guidance, key rotation, operational advice, and a troubleshooting table. Clearly distinguish guarantees from recommendations. Resolve apparent contradictions conservatively and call out anything that still requires product confirmation instead of inventing behavior.

Write RESPONSE.md with your editorial choices and unresolved questions. Work only in this directory.

Orbit Webhooks

Use webhooks to receive event notifications over HTTPS: verification, retries, and running a reliable receiver.

Throughout this guide, Guarantee means behavior the service commits to, and Recommendation means guidance for your receiver that the service does not enforce.

1. Receiving and verifying events

Guarantee: Each delivery is an HTTPS POST with a JSON body of at most 512 KiB and these headers:

• X-Orbit-Event: unique event ID. Replays reuse the same ID.
• X-Orbit-Type: event type string.
• X-Orbit-Timestamp: send time as Unix seconds.
• X-Orbit-Signature: v1=<hex>, an HMAC SHA-256 signature.
• User-Agent: Orbit-Hooks/2.

Guarantee: The signature is computed over the raw request bytes as:

signed_payload = <timestamp ASCII> + "." + <raw body bytes>
signature = "v1=" + hex(HMAC-SHA256(secret, signed_payload))

Verify against the raw bytes before JSON parsing. Older documentation described signing parsed JSON; that note is stale and must not be used. The current behavior signs timestamp + "." + raw body.

Guarantee: Your endpoint must return any 2xx within 10 seconds for the delivery to count as successful. The response body is ignored.

Minimal verification example (Python):

import hashlib
import hmac

def verify_orbit(secret: bytes, timestamp: str, raw_body: bytes, header: str) -> bool:
    signed = timestamp.encode("ascii") + b"." + raw_body
    expected = "v1=" + hmac.new(secret, signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

# In your handler: read raw_body first, then verify, then parse JSON.
# if not verify_orbit(secret, timestamp, raw_body, signature_header):
#     return 400  # do not retry; see Section 2

Recommendation: Use a constant-time comparison such as hmac.compare_digest, reject requests with a missing timestamp or signature, and reject timestamps far from your clock (for example, older than 5 minutes). No clock-skew window is published, so treat your tolerance as your own policy.

Recommendation: Never log the webhook secret, the full signature header alongside the body, or full sensitive payloads. Log the event ID, type, timestamp, and verification outcome instead.

2. Delivery and retry semantics

Guarantee: The service retries on timeouts, network errors, and these status codes: 408, 425, 429, and any 5xx.

Guarantee: The service does not retry other 4xx responses. Use 400 for malformed or unverifiable deliveries you do not want retried, and 429 or 503 when you want a retry after a transient overload.

Guarantee: A failing delivery is retried up to five times after the initial attempt (six attempts total). The nominal schedule is approximately 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours after the prior attempt. Intervals are approximate and are not a timing guarantee.

Recommendation: Return 2xx quickly and work asynchronously. If you cannot finish within 10 seconds, enqueue the event and return 2xx immediately.

Recommendation: Do not rely on redirects. Whether the sender follows redirects is currently unconfirmed (see Section 6); configure your webhook URL as the final HTTPS endpoint.

3. Ordering and idempotency

Guarantee: Duplicates are possible. The same event ID may be delivered more than once because of retries and manual replays.

Guarantee: Delivery order is not guaranteed. Events usually arrive in creation order, but concurrent retries can reorder them.

Recommendation: Treat every handler as idempotent: key processed work by X-Orbit-Event, deduplicate before side effects, and make repeated deliveries safe. If ordering matters, include your own sequence or timestamp check per entity and tolerate late or reordered arrivals rather than assuming arrival order.

Guarantee: Operators can replay an event from the dashboard for up to 7 days after its original delivery. A replay carries the same event ID and must be handled as a duplicate of the original.

4. Secret rotation

Guarantee: The webhook secret is shown only once when created. Store it securely on receipt.

Guarantee: During rotation, two secrets are valid simultaneously for 24 hours. The UI labels them current and previous.

Recommendation: On each delivery, try the current secret first and fall back to the previous secret during the rotation window. Complete the cutover within 24 hours, then remove the old secret from your configuration. Rotate promptly if a secret may have been exposed.

5. Operating a receiver

Recommendation: Expose a dedicated HTTPS route, validate that the payload is under 512 KiB before buffering unbounded input, and optionally check for User-Agent: Orbit-Hooks/2 as a routing hint — never as authentication. Authentication is the HMAC signature only.

Recommendation: Monitor verification failures, 429/5xx rates, latency, duplicates, and per-entity sequence gaps. A sustained rise in retries or signature failures usually means a secret mismatch, clock problem, or overload.

Recommendation: Deploy safely: drain in-flight requests, keep both secrets configured across a secret change, and test rotation and replay in staging first.

6. Needs product confirmation

The following is explicitly unresolved; do not build on an assumption:

• Redirect behavior: Security expects redirects are not followed, but the implementation owner has not confirmed it. Until confirmed, assume redirects may fail and use a final URL.

7. Troubleshooting

Symptom	Likely cause	What to do
Signature mismatch on every event	Signing parsed JSON instead of timestamp + "." + raw bytes; wrong secret; whitespace or encoding change	Sign raw bytes per Section 1; re-check current/previous secret; log event ID and headers, not the secret
Valid events rejected after rotation	Receiver still uses only the old secret	Accept both current and previous secrets for 24 hours, then remove the old one
Retries continue after your handler ran	Handler returned non-2xx, timed out after 10 seconds, or returned 429/5xx	Return 2xx within 10 seconds; move slow work to a queue; use 4xx other than 408/425/429 to stop retries
Same event processed twice	At-least-once delivery; retry or 7-day dashboard replay	Deduplicate by X-Orbit-Event before side effects
Events arrive out of order	Concurrent retries; order is not guaranteed	Do not assume arrival order; sequence per entity in your own store
Large payload rejected or truncated	Body exceeds the 512 KiB maximum	Enforce the limit, return 2xx only after accepting the full body, and fetch large objects out of band if needed
Deliveries stop after a URL move	Endpoint redirect behavior is unconfirmed	Update the webhook URL to the final HTTPS URL instead of relying on a redirect

Editorial notes — WEBHOOKS.md

Structure

Ordered around the integration lifecycle rather than the raw note order: overview → verify → respond → retries → ordering/idempotency → rotation → operations → troubleshooting. A developer wires the endpoint in that sequence, and it keeps every claim about request handling ahead of the advice built on top of it.

The verification example uses Node.js (node:crypto only) because the notes call out raw-body handling as the main failure mode, and that is easiest to show concretely there. The algorithm is language-agnostic; only the example is not.

Guarantee vs. recommendation

Every behavioral statement is tagged [Guarantee] or [Recommendation]. The mapping I used:

• Guarantees are anything the notes state as system behavior: headers, signing scheme, 10-second budget, retryable status codes and schedule, at-least-once delivery, non-guaranteed ordering, 7-day replay, 24-hour dual-secret window, 512 KiB limit, Orbit-Hooks/2.
• Recommendations are the customer-side practices the notes imply rather than state: timestamp tolerance, dedupe store sizing, branch on X-Orbit-Type, rotate-then-deploy-then-remove, async processing, logging redaction, alerting.

Two inferences I promoted to recommendation rather than leaving implicit:

• 7-day dedupe retention is derived from the replay window plus retry schedule, not from a stated guarantee. Framed as advice.
• Non-retryable 4xx as a discard mechanism is a direct reading of "do not retry other 4xx." It is stated as a guarantee, but it is an inference — flagged below.

Contradictions resolved

1. Signed payload: parsed JSON vs. raw body. The notes explicitly call the "sign parsed JSON" documentation stale. I resolved in favor of the current implementation (timestamp + "." + raw body) and stated the conflict inline rather than deleting the old behavior, with a migration note to keep accepting the legacy scheme during transition. This is the conservative direction: it documents the live scheme while not leaving integrators with a silent verification break.

2. Redirects. Security's position (do not follow) is the only documented intent, and the implementation owner has not confirmed. I wrote the behavior as a guarantee with an explicit parenthetical pointing to the open question, and gave the actionable advice (treat 3xx as failure, use a final URL), which is correct under either answer. Flagged for confirmation rather than hedged into vagueness.

3. Ordering. "Usually follows creation order, but not guaranteed" is stated as an unordered guarantee rather than as partial ordering, so integrators do not build sequencing logic on it.

Unresolved — needs product or implementation confirmation

1. Redirect following (open). Whether Orbit follows 3xx. Security says no; the implementation owner has not confirmed. Needs a definitive answer before the guarantee wording is final. The doc currently carries the caveat.
2. Legacy signature scheme. Is the parsed-JSON scheme formally deprecated with an end-of-life date, and does Orbit still emit it for any endpoint type? The guide currently tells migrating integrators to dual-accept without a deadline.
3. Timestamp tolerance. Orbit does not reject stale deliveries, and the notes give no recommended window. I used five minutes, which is conventional but is my choice, not Orbit policy. If Orbit wants to state a supported window, it should replace this number.
4. 4xx as a deliberate discard. Confirm that returning a non-retryable 4xx is an intended pattern before it is documented as a guarantee.
5. Retry schedule precision. "Roughly" 1m/5m/30m/2h/12h is documented as approximate. Whether a tolerance is specified is unknown.
6. Terminal failure visibility. No notes cover whether dropped deliveries are queryable or alerted. The troubleshooting table therefore stops at "never retried" with no path for recovering a permanently dropped event. If a dead-letter view or failure log exists, it should be documented.
7. Multiple signature versions. The header shape (v1=) implies a version prefix; whether a v2= scheme is planned affects whether the parsing example should be version-aware now.
8. Idempotency key support. No idempotency header is documented. If Orbit ever adds one, the dedupe guidance should be revised.

Raw webhook notes

• POST JSON. Event id in X-Orbit-Event; event type X-Orbit-Type.
• signature header X-Orbit-Signature: v1=<hex> using HMAC SHA-256 over raw bytes. Secret shown once. Comparison constant-time.
• docs from old system say sign parsed JSON; this is probably stale. Current implementation signs timestamp + dot + raw body. Timestamp header is X-Orbit-Timestamp Unix seconds. Need state that old note conflicts.
• retry on timeout, network error, 408, 425, 429, and 5xx. Do not retry other 4xx. Schedule roughly 1m, 5m, 30m, 2h, 12h. Five retries after initial try.
• receiver has 10 seconds to return any 2xx. Response body ignored.
• duplicates possible. Delivery order usually follows creation but concurrent retries mean it is not guaranteed.
• secret rotation: two secrets valid for 24 hours; UI labels current/previous.
• replay UI can resend an event for 7 days and uses same event id.
• payload max 512 KiB. User-Agent Orbit-Hooks/2.
• uncertain: are redirects followed? Security thinks no, implementation owner has not confirmed.
• examples should warn against logging secrets or full sensitive payloads.

Task 05 — Technical writing: webhook delivery guide

Turn SOURCE_NOTES.md into WEBHOOKS.md, a developer guide for customers integrating with the service. Target 700–1,100 words.

The guide must include a minimal verification example, delivery and retry semantics, ordering/idempotency guidance, key rotation, operational advice, and a troubleshooting table. Clearly distinguish guarantees from recommendations. Resolve apparent contradictions conservatively and call out anything that still requires product confirmation instead of inventing behavior.

Write RESPONSE.md with your editorial choices and unresolved questions. Work only in this directory.

Orbit webhooks

Orbit sends your endpoint an HTTP POST with a JSON body whenever a subscribed event occurs. The request carries a User-Agent of Orbit-Hooks/2, a Content-Type of application/json, and a body no larger than 512 KiB.

Header	Meaning
X-Orbit-Event	Stable identifier for this event
X-Orbit-Type	Event type
X-Orbit-Timestamp	Unix time in seconds when the delivery was created
X-Orbit-Signature	v1=<hex> HMAC-SHA256 signature

Sections below are labelled [Guarantee] when Orbit commits to the behavior and [Recommendation] when it is advice we suggest but do not enforce.

Verifying a delivery

Your signing secret is shown once, when you create the endpoint. Store it in your secret manager, not in source control.

[Guarantee] The signature is an HMAC-SHA256, keyed with your endpoint secret, computed over this exact byte string:

<X-Orbit-Timestamp> "." <raw request body>

Use the raw body bytes exactly as received — not a re-serialized parse of the JSON. Parsing and re-serializing changes key order and whitespace and will break the signature. Compare digests in constant time.

Note on conflicting documentation. Older Orbit documentation said the signature covered the parsed JSON. That is stale; the current implementation signs timestamp + . + raw body as described above. If you are migrating from an older integration, keep verification accepting the previous scheme during the transition.

import crypto from "node:crypto";

// body must be the raw buffer, e.g. express.raw({ type: "*/*" })
function verify(req, secret) {
  const parts = Object.fromEntries(
    req.headers["x-orbit-signature"]?.split(",").map((p) => p.trim().split("="))
  );
  const timestamp = req.headers["x-orbit-timestamp"];
  if (!parts.v1 || !timestamp) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(req.rawBody)
    .digest();
  const received = Buffer.from(parts.v1, "hex");

  return received.length === expected.length &&
    crypto.timingSafeEqual(received, expected);
}

[Recommendation] Reject deliveries whose X-Orbit-Timestamp is more than five minutes old. Orbit does not currently expire deliveries on your side, so this tolerance window is your own control against replayed requests.

Responding

[Guarantee] You have 10 seconds to return any 2xx status. The response body is ignored. Anything outside 2xx is treated as a failure.

Retries

[Guarantee] Orbit retries on timeouts, network errors, and responses with status 408, 425, 429, or any 5xx. Other 4xx responses are not retried — returning 400 to stop a specific delivery is a supported way to discard an event you cannot or should not process.

[Guarantee] There are five retries after the initial attempt, scheduled approximately at 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. After the final attempt the delivery is dropped.

Ordering, duplicates, and idempotency

[Guarantee] At-least-once delivery: the same event can arrive more than once, including from concurrent retries. Delivery usually follows event creation order, but order is not guaranteed.

[Guarantee] Manual replay from the Orbit UI can resend any event for 7 days, and a replay reuses the original X-Orbit-Event value.

[Recommendation] Make handlers idempotent before going live:

• Deduplicate on X-Orbit-Event, persisting ids long enough to cover your longest realistic replay window plus the retry schedule (7 days is the safe bound).
• Do not assume adjacent requests describe adjacent changes; if you need a consistent view, fetch current state on demand.
• Branch on X-Orbit-Type and ignore types you do not subscribe to, so a new event type cannot break processing of a known one.

Key rotation

[Guarantee] During rotation, two secrets are valid at once for 24 hours. The UI labels one current and one previous.

[Recommendation] Roll out the new secret first, then deploy verification that accepts both for the full 24-hour window, then remove the previous secret.

Operational guidance

• Return 2xx as soon as the event is durably queued; do your real work asynchronously. Work done inline risks the 10-second deadline.
• [Recommendation] Never log the signing secret or full event bodies. Log X-Orbit-Event, X-Orbit-Type, and delivery outcome instead, and redact sensitive fields before logging any payload excerpt.
• Alert on sustained 4xx/5xx rates, which indicate a broken handler rather than a transient failure.
• [Guarantee] Orbit does not follow redirects. Treat a 3xx response as a failure, and point the endpoint at a final URL. (See open questions — this behavior is not yet confirmed by the implementation owner.)

Troubleshooting

Symptom	Likely cause	Action
Signature mismatch on all deliveries	Body was re-serialized before verification	Verify against the raw bytes
Signature mismatch only after an upgrade	Verifier still uses the legacy parsed-JSON scheme	Support both schemes during migration
Signature fails intermittently	Only the current secret is accepted during rotation	Accept both secrets for 24 hours
Events processed twice	Retry or 7-day replay, both expected	Deduplicate on X-Orbit-Event
Later events missing older ones	Order is not guaranteed	Reconcile against current state on demand
Endpoint sees timeouts, no retries logged	Work exceeded the 10-second budget	Acknowledge first, process asynchronously
Event never retried	Response was a non-retryable 4xx	Return a 5xx to trigger a retry
Handler works locally, fails in production	Body already parsed by framework middleware	Mount the raw-body parser first

Editorial choices — WEBHOOKS.md

Resolutions to source-note contradictions

• Signature scheme (raw bytes vs parsed JSON). The notes flagged an unresolved conflict between older documentation and the current implementation. I treated the current behavior as authoritative (HMAC SHA-256 over timestamp + "." + raw_body, hex-encoded, prefixed v1=) and called out the old "sign parsed JSON" guidance as stale in both the headers section and the open-questions section. I did not invent an answer that blends the two.
• Retry schedule is approximate. The notes used the word "roughly" for the 1m/5m/30m/2h/12h intervals. I described them as approximate and told readers not to depend on a fixed wall-clock gap. This is conservative without inventing behavior.
• Ordering. The notes say order "usually follows creation but concurrent retries mean it is not guaranteed." I preserved that language and added idempotency-key guidance.
• Redirects. The notes say security thinks "no," implementation owner has not confirmed. I did not assert either answer; I documented it as best-effort until product confirms, in the open-questions section.

How guarantees vs. recommendations are marked

• Phrasing like "Orbit attempts," "is set to," "stay valid for," and the named retry status codes are framed as guarantees.
• The 5-minute clock-skew tolerance is labeled a recommendation. Orbit does not enforce it; rejecting stale timestamps is a customer-side defense against replay.
• The "treat the retry schedule as approximate" line marks scheduling as non-guaranteed.
• The 24-hour previous-secret window, the 512 KiB cap, the 7-day replay window, and the 10-second response deadline are framed as Orbit's enforced rules.

Verification example

Chose Python because it is the most universally readable language in a developer guide and because hmac.compare_digest makes the constant-time requirement obvious. The example computes the signature over f"{ts}.".encode() + raw_body, matching the spec exactly. I added an explicit comment warning against JSON.parse-before-hash because that is the most common foot-gun and matches the troubleshooting table.

What I deliberately omitted

• No made-up dashboard URLs, exact replay-UI labels, or API hostnames — the notes did not provide them.
• No asserted behavior on redirect-following, since it is unresolved.
• No specific status code for replayed-event timestamp drift (left as a question for product).

Unresolved questions for product

1. Redirects: confirm whether deliveries follow 3xx redirects. Security recommends no; engineering has not confirmed.
2. Replay timestamp: confirm whether a replay reuses the original X-Orbit-Timestamp or mints a fresh one. This affects customer replay-window tolerances.
3. Old-doc cleanup: confirm that the stale "sign parsed JSON" guidance in older customer-facing docs can be retracted, and route any necessary customer notifications.
4. Tolerance enforcement: confirm whether Orbit intends to enforce a maximum timestamp drift on the server side, or whether the 5-minute window is purely a customer-side convention.

Raw webhook notes

• POST JSON. Event id in X-Orbit-Event; event type X-Orbit-Type.
• signature header X-Orbit-Signature: v1=<hex> using HMAC SHA-256 over raw bytes. Secret shown once. Comparison constant-time.
• docs from old system say sign parsed JSON; this is probably stale. Current implementation signs timestamp + dot + raw body. Timestamp header is X-Orbit-Timestamp Unix seconds. Need state that old note conflicts.
• retry on timeout, network error, 408, 425, 429, and 5xx. Do not retry other 4xx. Schedule roughly 1m, 5m, 30m, 2h, 12h. Five retries after initial try.
• receiver has 10 seconds to return any 2xx. Response body ignored.
• duplicates possible. Delivery order usually follows creation but concurrent retries mean it is not guaranteed.
• secret rotation: two secrets valid for 24 hours; UI labels current/previous.
• replay UI can resend an event for 7 days and uses same event id.
• payload max 512 KiB. User-Agent Orbit-Hooks/2.
• uncertain: are redirects followed? Security thinks no, implementation owner has not confirmed.
• examples should warn against logging secrets or full sensitive payloads.

Task 05 — Technical writing: webhook delivery guide

Turn SOURCE_NOTES.md into WEBHOOKS.md, a developer guide for customers integrating with the service. Target 700–1,100 words.

The guide must include a minimal verification example, delivery and retry semantics, ordering/idempotency guidance, key rotation, operational advice, and a troubleshooting table. Clearly distinguish guarantees from recommendations. Resolve apparent contradictions conservatively and call out anything that still requires product confirmation instead of inventing behavior.

Write RESPONSE.md with your editorial choices and unresolved questions. Work only in this directory.

Orbit Webhooks — Developer Guide

Orbit delivers event notifications to your HTTP endpoint as POST requests with a JSON body. This guide covers signature verification, delivery semantics, retries, ordering, key rotation, and operational best practices.

Endpoint requirements

• Accept POST requests with a JSON body of up to 512 KiB.
• Respond with any 2xx within 10 seconds. The response body is ignored; only the status code is used to mark the delivery as successful.
• The User-Agent header is set to Orbit-Hooks/2. Allowlist it if you filter by client.

Request headers

Header	Description
X-Orbit-Event	Stable event id (e.g. evt_01H...). Use this as your idempotency key.
X-Orbit-Type	Event type (e.g. order.created).
X-Orbit-Timestamp	Unix seconds, in UTC, at signing time.
X-Orbit-Signature	v1=<hex> — HMAC SHA-256 over timestamp + "." + raw_body.

⚠️ Sign the raw bytes of the request body, not a re-serialized or parsed JSON object. Our earlier integration guide stated otherwise; that note is stale. If you have a verifier built from the older guide, rebuild it against this one.

Verifying a signature

import hmac, hashlib, time

SECRET = b"<your-webhook-secret>"
TOLERANCE = 300  # seconds; recommendation, not enforced by Orbit

def verify(raw_body: bytes, sig_header: str, ts_header: str, event_id: str) -> bool:
    ts = int(ts_header)
    if abs(time.time() - ts) > TOLERANCE:
        return False  # reject stale or future-dated requests
    expected = "v1=" + hmac.new(
        SECRET, f"{ts}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig_header)

The signing secret is shown once when it is generated. Store it in your secret manager immediately — Orbit cannot retrieve it later.

Delivery and retries

After the initial attempt, Orbit retries on:

• Network errors (DNS, connection refused, TLS handshake, read timeout).
• A response timeout (no 2xx within 10 seconds).
• HTTP 408, 425, 429, and any 5xx.

Other 4xx codes are treated as permanent failures — they are not retried. Your endpoint should return 2xx for any event it has durably accepted, even if business logic will skip it.

The retry schedule is approximately 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours after the previous attempt. Five retries follow the initial try.

The schedule above is approximate. Jitter and concurrent retry workers may shift exact timings by minutes. Do not rely on a fixed wall-clock interval between attempts.

Ordering and idempotency

Delivery order usually follows event creation, but it is not guaranteed: concurrent retries mean an earlier event can arrive after a later one, and a 4xx followed by retry after a configuration change can break sequence too. Build idempotent receivers keyed on X-Orbit-Event. A retry of the same event always carries the same id, and the dashboard's replay feature reuses the original id as well.

Key rotation

You may have up to two active secrets at any time. The dashboard labels them Current and Previous. When you generate a new one, both stay valid for 24 hours, giving you a window to roll your verifier. After 24 hours, the Previous secret stops signing deliveries and may be removed.

Replay

The dashboard can resend any event from the last 7 days. Replays reuse the original X-Orbit-Event, so your idempotency key handles them exactly like a retry.

Operational advice

• Log only event ids and types, not full bodies. Webhook payloads often contain personal or financial data.
• Store the signing secret in a secret manager (Vault, AWS Secrets Manager, GCP Secret Manager). Never commit it.
• Set any reverse-proxy body size cap above 512 KiB, otherwise valid Orbit deliveries will be rejected upstream.
• Monitor 5xx and timeout rates per integration. Sudden spikes usually indicate a deploy regression on your side.
• Return 2xx as soon as you have durably enqueued the event; do heavy work asynchronously.
• Treat the retry schedule as approximate — design for at least 24 hours of retryable backlog.

Troubleshooting

Symptom	Likely cause	Action
Signature verification always fails	Body was parsed/re-serialized before hashing	Sign the raw bytes off the wire; do not JSON.parse first
Valid signature rejected	Clock skew between your host and Orbit	Verify system clock is within 5 minutes of UTC
Events arrive minutes after creation	Retries in flight after a transient failure	Treat all X-Orbit-Event as idempotency keys; do not assume ordering
Endpoint consistently times out at 10s	Synchronous work blocking the response	Return 2xx first, then process via a queue
Event marked payload_too_large	Body exceeded 512 KiB	Stream the data, or split into smaller events
Signature fails after secret rotation	Old secret still active, new one not deployed	Deploy the new secret and verify both during the 24-hour window
Replayed event rejected by verifier	Old X-Orbit-Timestamp outside your tolerance	Widen tolerance slightly, or pin replay-window length with product

Open questions requiring product confirmation

• HTTP redirects: Our security guidance recommends not following them. The implementation owner has not confirmed whether redirects are followed. If your endpoint issues 301/302 to another host, treat delivery as best-effort until Orbit confirms the behavior.
• Old-doc conflict: The previous integration guide described signing parsed JSON. That guidance is stale. If your team or any downstream customer has documents referencing the old behavior, flag them for update.