Human Review troubleshooting

Start with the review case ID, event ID, and delivery ID. Keep them with the timestamp and redacted error for the failed step. Do not share webhook secrets, credentials, checkpoints, withheld output, or full callback bodies.

Use the Core Human Review lifecycle guide to confirm the expected outcome, directive, and resume mode before changing application state.

A case was not assigned

1. Confirm that the reviewer is active in the same tenant.
2. Confirm the reviewer can access the application.
3. Confirm the reviewer has the required capability.
4. Confirm the configured group contains an individually authenticated, eligible member.
5. Check the configured Administrator fallback and its eligibility.
6. Repair the assignment without creating a second review case.

Possession of the email, mailbox, provider group, or callback credential does not make a person eligible.

Reviewer email did not arrive

Check Inbox first; the review may be waiting there even if email did not arrive. Review the address, notification schedule, bounce or suppression state, delivery attempts, and authenticated case link. Do not ask the reviewer to decide by replying to email.

Signature verification failed

Check these values in order:

1. The body is no more than 65,536 bytes.
2. The receiver used the exact raw bytes before JSON parsing.
3. webhook-timestamp is Unix seconds and within 300 seconds of the receiver’s clock. Check the host clock if every request fails here.
4. webhook-id, webhook-timestamp, and webhook-signature each arrived once.
5. The signed content is webhook-id, a period, webhook-timestamp, a period, and the raw body.
6. The receiver trusts the right key set. It loads it from /.well-known/veriproof-webhook-keys.json on the endpoint the SDK uses, or from the pinned key set you configured. A pinned set must include the key ID shown in webhook-key-version.
7. The signature starts with v1a,. Callbacks never use v1 (HMAC) signatures.

If the receiver answers 503 because it couldn’t load the key set, check that it can reach your VeriProof endpoint over HTTPS. VeriProof retries the delivery.

Do not weaken verification to recover delivery. Repair the receiver, send a synthetic test, and then replay.

The callback was received twice

Use eventId from the verified body for the business event and the webhook-id header, which equals deliveryId, for the delivery. Atomically look up the stored result. For an exact replay, return the prior receipt with HTTP 200 and replayed: true. Return HTTP 409 when the same identity conflicts with the stored body or bindings. Do not claim the continuation twice.

The outcome does not match local state

Reject or quarantine the outcome when any tenant, application, environment, case, workflow instance, branch, continuation, checkpoint generation, state fingerprint, policy decision, event sequence, decision version, callback registration version, or expiry value does not match.

Do not select a continuation by session, the latest pause, action type, or branch label.

Approval arrived but the checkpoint is missing

Do not recreate state from the callback and do not run the protected action. Record the incident, preserve the decision and delivery evidence, and report failed or superseded through the execution acknowledgment when that state is known. Cancel remaining review work with checkpoint_unavailable when the case is still cancellable.

Follow-up resumed the application

follow_up_required must carry remain_paused; it must not resume work. Stop the affected worker, preserve the callback and claim records, confirm whether an external side effect occurred, and escalate for incident review. A later decision must use a later decision version and the same exact case binding.

VeriProof shows delivery but not application execution

A durable receipt proves only that the application stored the outcome. Check the application’s continuation worker, atomic-claim record, local policy re-evaluation, and acknowledgment request. Do not change the UI or audit record to resumed until the application reports resumed.

The acknowledgment was refused with durable_receipt_pending

Your application acknowledged before VeriProof finished recording the callback receipt. This is expected when the application resumes right away. Nothing was recorded; send the same acknowledgment after the Retry-After interval. The SDKs retry it for you and keep it in the review store if the receipt takes longer. If it never succeeds, check the delivery attempts for that delivery ID: the receipt is recorded only when your receiver returns a valid durable receipt.

A revision response ran the original payload

response_submitted with route_to_revision must enter the application-owned revision path without executing the superseded protected payload. Stop the worker, preserve the callback, claim, response digest, and idempotency records, determine whether a side effect occurred, and escalate for incident review. Do not switch the result to resume_with_response or replay it to hide the failure.

Cancellation returned a conflict

Confirm the expected case version, continuation, checkpoint generation, and idempotency key. An exact replay should return the prior result. A different request with the same idempotency key is a conflict. Refresh the case state before deciding whether a new cancellation is valid.

Before replay

• repair the endpoint or key;
• confirm the callback registration version;
• confirm the outcome and delivery have not expired;
• confirm the exact continuation still exists;
• confirm no later decision already superseded the event;
• send a synthetic test when the repair changed signing or parsing; and
• keep the original event identity so replay cannot create another side effect.