asyncapi: 3.0.0 info: title: Ingo Check Protect — Webhooks version: 1.0.0 description: > Real-time event notifications delivered by the Ingo Check Protect API to your registered webhook URL. Check Protect always sends a webhook for every transaction request, carrying the final risk score. If the original request was routed to the Ingo Risk Center for manual review (synchronous response `transactionRiskScore: 1`), a second webhook fires after review completes with the updated score. Events are POSTed as JSON to your configured webhook URL. Return any 2xx status to acknowledge receipt. Non-2xx responses are retried every 30 minutes for up to 24 hours by default (retry frequency, intervals, and max attempts are configurable per endpoint). Use `metadata.webhookId` as your deduplication key — events may be redelivered under transient failure. Idempotent replays of the score endpoint (`X-Idempotent: true`) do NOT fire webhooks. **Supported auth schemes** for the webhook endpoint: Bearer Token (OAuth 2.0) preferred, Basic Base64 `UserId:Password`, or Client Certificates. contact: name: Ingo Payments Integrations url: https://developers.ingopayments.com defaultContentType: application/json servers: webhook: host: your-webhook-endpoint.example.com protocol: https description: >- Ingo delivers Check Protect events via HTTP POST to your registered HTTPS endpoint (TLS 1.2 minimum). channels: CheckProtectTransactionApprove: address: checkprotect.transaction.approve.v1 title: Transaction Approved tags: - name: Check Protect description: > Fired when a transaction scores in the approval range (continuous score `300`–`1000`). For most synchronous scores this webhook is the second confirmation of the result already returned to your back-end; you can use it for receipt generation, audit logging, or asynchronous workflow triggers. messages: CheckProtectTransactionApproveMessage: $ref: '#/components/messages/CheckProtectWebhookMessage' CheckProtectTransactionDecline: address: checkprotect.transaction.decline.v1 title: Transaction Declined tags: - name: Check Protect description: > Fired when a transaction scores in a discrete negative bucket (`2`–`299`) indicating high risk or fraud. The score returned matches what was sent on the synchronous `/deposit/score` response. messages: CheckProtectTransactionDeclineMessage: $ref: '#/components/messages/CheckProtectWebhookMessage' CheckProtectTransactionManualReview: address: checkprotect.transaction.manualreview.v1 title: Manual Review Decision tags: - name: Check Protect description: > Fired after the Ingo Risk Center completes review of a transaction that synchronously returned `transactionRiskScore: 1`. The `transactionRiskScore` in this webhook is the final decisioning score, not the placeholder `1` returned synchronously. Available only to clients opted into Ingo Risk Center review services. messages: CheckProtectTransactionManualReviewMessage: $ref: '#/components/messages/CheckProtectWebhookMessage' components: messages: CheckProtectWebhookMessage: name: CheckProtectWebhook title: Check Protect Webhook Payload summary: Score decision for a single Check Protect transaction. contentType: application/json payload: $ref: '#/components/schemas/CheckProtectWebhookPayload' schemas: CheckProtectWebhookPayload: type: object required: - metadata - eventData description: > Two-part payload structure: `metadata` carries delivery info (webhook ID, topic, timestamp), `eventData` carries the scoring result and echoes the client identifiers. properties: metadata: $ref: '#/components/schemas/Metadata' eventData: $ref: '#/components/schemas/EventData' example: eventData: requestId: c8a456fb-aa42-4c88-8254-3923dd3bd09e transactionRiskEngineScore: 350 transactionRiskScore: 456 ingoTransactionId: 07c2b3e5-7f67-4749-848c-f1280a4744fe clientData: customerId: 03324f6e-f959-433a-8ece-3673ae2a399e transactionId: 36dcd695-ef1c-48e3-953d-5eb9cf2ea84b clientId: 323c9fb8-d24e-4c5b-817b-6e553a574fa9 ingoCheckAmountInCents: 62859 ingoCustomerId: 62e51ee7-f6c3-49f9-bff8-f2c4fac07b75 checkType: PersonalCheck checkMakerName: Regions metadata: topicName: checkprotect.transaction.approve.v1 webhookId: ab45d8a2-98a6-4eed-9ac4-e151b640a435 unixTimestamp: '1638219167' Metadata: type: object required: - webhookId - topicName - unixTimestamp description: Delivery metadata for the webhook event. properties: webhookId: type: string maxLength: 50 format: uuid description: >- Unique GUID identifier for this webhook delivery. Use as your idempotency / deduplication key. topicName: type: string maxLength: 255 description: > The specific event topic. Convention: `...v`. Current topics: `checkprotect.transaction.approve.v1`, `checkprotect.transaction.decline.v1`, `checkprotect.transaction.manualreview.v1`. unixTimestamp: type: string maxLength: 10 description: Unix epoch timestamp (seconds) when the webhook was published. EventData: type: object required: - requestId - ingoCustomerId - ingoTransactionId - checkType - checkMakerName - ingoCheckAmountInCents - transactionRiskScore - transactionRiskEngineScore - clientData description: Transaction-level scoring result. properties: requestId: type: string maxLength: 50 description: >- Ingo-assigned identifier associated with the original `/deposit/score` request. ingoCustomerId: type: string maxLength: 50 format: uuid description: Ingo-assigned internal customer identifier. ingoTransactionId: type: string maxLength: 50 format: uuid description: Ingo-assigned internal transaction identifier. checkType: type: string maxLength: 50 description: Identified check type (e.g., `PersonalCheck`, `Government`). checkMakerName: type: string maxLength: 50 description: >- Recognized maker of the check (may be `null` for some manual-review cases). ingoCheckAmountInCents: type: integer description: Ingo-derived check amount in cents. transactionRiskScore: type: integer description: > Final Ingo risk score for this transaction. For approve/decline webhooks, this matches the synchronous score. For manual-review webhooks, this is the post-review score (the synchronous response carried `1`). transactionRiskEngineScore: type: integer description: > Raw risk engine score before any client-configured scoring overrides. Typically matches `transactionRiskScore`; may diverge when overrides apply. clientData: $ref: '#/components/schemas/ClientData' ClientData: type: object required: - clientId - transactionId - customerId description: >- Echo of the client-supplied identifiers from the original score request, for cross-system correlation. properties: clientId: type: string maxLength: 50 format: uuid description: Echo of the Ingo-assigned client ID sent with the original request. transactionId: type: string maxLength: 50 description: >- Echo of the client-assigned `transactionId` sent with the original request. customerId: type: string maxLength: 50 description: >- Echo of the client-assigned `customerId` sent with the original request.