fraud agent failed to parse onfido webhook check result payload

TL;DR

Onfido webhook payloads are compact: an event action, a resource type, and an object containing ids and, for completed checks, a result. Agents break when they expect the full check detail inside the webhook, read a field the current API version renamed, or reject the payload for a missing optional field. Log one raw failing payload untouched, map it against the Onfido webhook reference for your API version, and treat the webhook as a trigger: extract the check and applicant ids, then fetch the full check result from the API. That fetch pattern survives schema changes that a payload scraping pattern does not.

fraud agent failed to parse onfido webhook check result payload

Use this when

• The agent errors or crashes on Onfido check webhooks.
• Webhooks arrive and the Onfido dashboard shows results the agent never records.
• Failures started after an Onfido API version or workflow change.

Not for this skill when

• No Onfido webhooks arrive at all. Check subscription and endpoint delivery first.
• The API fetch of the check fails with an auth error. That is credentials, not payload parsing.

Steps

1. Capture one raw webhook body exactly as received, before parsing, and save it as the failing fixture. Verify: you have an untouched sample payload from production.
2. Map its fields against the Onfido webhook documentation for your API version, noting the action values for workflow and check events and which fields are actually guaranteed. Verify: the mapping lists the fields your parser may rely on.
3. Rewrite the handler to parse only the guaranteed fields, then fetch the full check by id from the API and store that result on the case. Verify: the fixture payload processes end to end in staging and the case shows the fetched result.
4. Make unknown actions and missing optional fields non fatal: log them and continue, alerting only when the check id itself is unusable. Verify: a staged payload with an extra field processes without error.
5. Add schema drift monitoring: a weekly sample of raw payloads diffed against the parser expectations, so the next Onfido change is a ticket, not an outage. Verify: the drift check exists and its last run is recorded.

Variant phrasings

onfido webhook parse error agent

Parse error phrasing.

agent cannot read onfido check result webhook

Result reading phrasing.

onfido webhook payload schema changed

Schema drift phrasing.

Compatibility: Onfido webhooks across API versions, with webhook signature verification per Onfido docs. Always pair parsing with signature verification and an API fetch for authoritative results.

Why it happens

Webhook payloads are notifications, not documents, and vendors evolve them: new actions for new products, fields that move between the webhook and the API as versions change. An agent that scrapes the notification as if it were the record breaks on the first evolution, while an agent that treats it as a pointer to the record survives every change that keeps the ids stable.

Edge cases / pitfalls

• Verify the webhook signature before parsing in production. A parser that accepts anything will eventually process a forged completion.
• Workflow run events and check events have different shapes. Route them by action before parsing, not after a failure.
• Keep raw payloads for failed events. Deleting the evidence of a parse failure guarantees a second occurrence.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Kzc3aIvz3Khmg0vqahWP2w