Recover webhook deliveries

Before you replay

You are the authorised company integration operator. Use the endpoint company’s Live key; obtain webhooks:replay only if recovery is your responsibility. Inspection accepts webhooks:read, webhooks:write, webhooks:replay or *. All requests below use https://api.kuahr.com. Test and Live keys and SDK setup apply.

Repair and inspect

Fix the receiver first and keep deduplication on the original event ID. A live API key may inspect delivery history with webhooks:read, webhooks:write, webhooks:replay or *; queueing a replay requires webhooks:replay or *; the company’s owner controls the underlying settings permission. Test keys cannot manage live webhooks.

Inspect retained history, then queue the exhausted delivery with a reason (3–1000 characters) and a request key (at most 100 characters). Persist the key and reason before sending the request. If the response is interrupted, retry that exact request rather than generating a new key. Reusing a key with different terms or a different caller is a conflict.

const history = await kua.webhooks.history(endpointId, deliveryId);
// Load this object from your durable recovery record on a retry.
const recovery = { requestKey: "your-stored-recovery-id", reason: "Receiver repaired and event deduplication checked" };
const accepted = await kua.webhooks.replay(endpointId, deliveryId, recovery);
// accepted.status === "Pending": queued, not delivered.
const deliveries = await kua.webhooks.deliveries(endpointId);

history = kua.webhooks.history(endpoint_id, delivery_id)
# Load the same values from your durable recovery record on a retry.
accepted = kua.webhooks.replay(
    endpoint_id, delivery_id,
    request_key="your-stored-recovery-id",
    reason="Receiver repaired and event deduplication checked",
)
# accepted.status == "Pending": queued, not delivered.
deliveries = kua.webhooks.deliveries(endpoint_id)

curl "https://api.kuahr.com/v1/webhooks/{endpointId}/deliveries/{deliveryId}/history" \
  -H "X-Api-Key: kua_live_your_key_here"

curl "https://api.kuahr.com/v1/webhooks/{endpointId}/deliveries/{deliveryId}/replay" \
  -X POST -H "X-Api-Key: kua_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"requestKey":"your-stored-recovery-id","reason":"Receiver repaired and event deduplication checked"}'

202 accepts the replay into the queue. It does not prove the receiver accepted the event or that its business action completed. The original event and delivery IDs, cumulative attempts and retained history remain available; replay grants another six attempts. Pending deliveries continue their automatic retries and cannot be replayed manually. An inactive endpoint must be enabled before recovery. An attempt with outcome Unknown has no confirmed completion; reconcile it using the event ID instead of assuming the receiver did nothing.

History contains attempts and replays, including attempt outcomes and the reason/actor/time for manual recovery. Older cumulative attempts may predate retained attempt records. No secret or raw request payload is included in recovery history.

Recovery limits are three replays per delivery per 24 hours and 100 per endpoint per hour. 409 reports a state or request-key conflict; refresh status and inspect the existing request. 429 reports a recovery limit. A lost response or server error leaves the outcome unknown; preserve the original recovery key.

Verify the replay

Read deliveries and retained history until the original delivery is Succeeded or again Exhausted; Pending still needs monitoring. Match event ID, delivery ID, attempts and the returned replayId against your persisted request key and reason. History does not return the request key. Then confirm your receiver’s durable inbox and the destination business outcome. A 2xx alone does not prove a downstream payment, email or synchronisation completed.

If the receiver remains unhealthy, stop new manual replays, fix it and reconcile uncertain events before spending another replay allowance. A deleted/revoked endpoint or foreign-company ID is not recoverable with this key. Company administrators use their Owner-controlled settings permissions; exceptional Kua-operator recovery is separately authorised and audited, not an entitlement of a company API key.

Done when: the retained delivery/history and receiver records agree, the original event caused at most one effect, and the recovery reason/actor/request key are retained. Continue to signing-secret rotation if the failure involved a credential change.