Receive signed delivery notifications

OrbitForge is an event routing API for teams that move operational telemetry between services. This guide explains how to register an HTTPS delivery endpoint without losing the context required to recover from partial failures. Examples use the fictional sandbox host api.orbitforge.example and a workspace called ws_lab. Replace these values with the workspace identifier returned by your own control plane. Sandbox traffic is isolated from production billing and does not appear in production retention reports.

Contract and prerequisites

Each notification has a stable delivery identifier even when the same notification is retried. Before you begin, create a sandbox workspace, select its region, and grant a service account the narrowest permission needed for this workflow. The workspace identifier is required on every request. Region selection happens when the workspace is provisioned; sending the same identifier to another regional endpoint does not migrate its contents. Treat a missing resource response as a configuration problem until you have checked both the identifier and the endpoint.

The API accepts UTF-8 JSON and returns a request identifier in every response. Record that identifier with your application trace, but do not log bearer credentials or entire customer payloads. Dates must use an explicit offset; examples use UTC to keep comparisons unambiguous. Empty strings and omitted properties have different meanings. An omitted optional field selects the documented default, while an empty string is validated as a supplied value and may be rejected.

Request example

Use the following request as a connectivity check before adding application concurrency. The example deliberately requests a small result so you can inspect the full response and compare it with your local ledger. Supply a real sandbox token through your process environment rather than committing it to a source file.

curl --fail-with-body 'https://api.orbitforge.example/v1/webhooks' \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H 'Orbit-Workspace: ws_lab' \
  -H 'Accept: application/json'

A successful response includes a stable resource identifier, its current state, and the server observation time. Do not infer completion from the HTTP status alone. Accepted work may still be pending in a regional queue. If the response includes an operation reference, follow that reference until it reaches a terminal state before making dependent changes. Preserve the original response when diagnosing a discrepancy; a later read may show a newer state.

Response fields

These fields form the minimum response contract. Additional fields may appear without a new API version, so parsers should ignore unknown properties while still validating the fields they actually use. A missing required field is a protocol error and should be reported with the request identifier. Do not silently replace a missing state with a success value, because that would turn a recoverable integration failure into an incorrect business decision.

Failure handling

Transport failures leave the outcome uncertain when the server may already have received the request. Read the current resource or operation status before constructing a replacement mutation. Validation errors are deterministic for the same body and should be corrected rather than retried. Permission errors require a scope or workspace change. For throttling and temporary server errors, honor the retry delay and cap the number of attempts so background recovery cannot overwhelm foreground traffic.

Operational verification

Verify the signature over the original request bytes before parsing JSON or acknowledging delivery. During rollout, compare a sample of server identifiers with the identifiers stored by your application. Measure both request latency and the time until the resulting state becomes usable. Those measurements answer different questions: a fast acknowledgement can still precede a long processing delay. Alert on sustained changes in terminal failure rate rather than on a single slow response, and include the region in every dashboard dimension.

Keep a compact recovery log containing the request identifier, workspace, resource identifier, attempt count, and last observed state. Retain it for at least the maximum retry horizon of your application. During an incident, pause new work before replaying that log, select a bounded batch, and compare the resulting counts with the original intent. Resume normal traffic only after a second read confirms the expected state. This procedure makes recovery auditable without copying sensitive event bodies into diagnostic storage.

Signature and acknowledgement

OrbitForge sends Orbit-Signature and Orbit-Timestamp headers with each notification. Compute HMAC-SHA256 over the timestamp, a period, and the raw request body using the endpoint signing secret. Compare the hexadecimal signature in constant time. Reject timestamps more than five minutes from the receiver clock to reduce replay exposure. Signature verification must happen before any transformation such as whitespace normalization, character decoding replacement, or JSON reserialization, because those transformations change the signed bytes.

Return a 2xx response only after the delivery identifier and work item have been durably queued. The delivery deadline is ten seconds. Business processing should happen outside the request handler so a slow downstream dependency does not cause duplicate delivery storms. Retry attempts retain the delivery identifier and use a fresh signature timestamp. Keep deduplication entries for seventy-two hours, which exceeds the forty-eight-hour delivery retry horizon. When rotating endpoint secrets, accept both active secrets during the configured overlap period.