Endpoint lifecycle

An endpoint contains one HTTPS URL, a description, an explicit event selection, a lifecycle state,
and safe signing-secret metadata. The plaintext secret is returned only by create and rotate.

Delivery health

Each endpoint includes a production-only health summary. Manual and resume tests never change it.

• unknown: Oway has not made a production delivery attempt.
• healthy: the latest production attempt succeeded.
• degraded: one or two consecutive production attempts failed.
• failing: three or more consecutive production attempts failed.

Use consecutive_failures, last_attempt_at, and last_success_at to show useful status without
polling or exposing response bodies. A successful production attempt resets
consecutive_failures to zero.

Idempotent effects

Send a unique printable ASCII Idempotency-Key (maximum 255 characters) on create, pause, resume,
rotate, test, and replay. The key is scoped to your tenant, method, and path for 24 hours.
Repeating the same request returns the original result; using the key for different bytes returns
idempotency_key_conflict.

Safe concurrent updates

GET /v1/webhooks/endpoints/{endpoint_id} returns a strong ETag, such as "4". Supply that exact
value in If-Match when patching:

curl --fail-with-body \
  --request PATCH \
  --header "Authorization: Bearer $OWAY_API_TOKEN" \
  --header "x-oway-api-key: $OWAY_COMPANY_API_KEY" \
  --header 'If-Match: "4"' \
  --header "Content-Type: application/json" \
  --data '{"event_types":["shipment.delivered","shipment.exception"]}' \
  "https://api.oway.io/v1/webhooks/endpoints/$OWAY_ENDPOINT_ID"

On precondition_failed, read the endpoint again, reconcile your intended change, and retry with
the new ETag.

Pause, resume, and archive

• Pause stops production delivery without deleting configuration.
• Resume first revalidates the URL and queues a signed test. The endpoint becomes active only after
  that test returns 2xx.
• Archive is permanent. Archived endpoints cannot be changed or resumed and do not count toward
  delivery.

Oway also pauses an endpoint after 410 Gone, a destination-policy rejection, retry exhaustion,
or the 72-hour retry window.

Rotate a secret

Rotation returns a new whsec_... secret once. For the next 24 hours, Oway signs with both the new
and previous keys. Deploy the new key, accept either key during overlap, then remove the old key
after previous_secret_expires_at.

Never rotate repeatedly to recover a lost response. Retry the original request with the same
Idempotency-Key so the one-time response can be returned from the idempotency record.

Limits

• 25 active or paused endpoints per tenant/audience
• 2,048 bytes per HTTPS URL
• 200 Unicode scalar values per description
• 100 records per collection page
• 64 KiB per management request body