The "Check Protect" webhook component is built to support "Transaction Scoring" decisions
You will need to create and register your static webhook URL to receive webhook updates. The URL endpoint you create to receive webhook requests must be configured to support HTTPS using TLS1.2 or higher.
TLS 1.3 (suites in server-preferred order)
- TLS_AES_256_GCM_SHA384 (0x1302) ECDH x25519 (eq. 3072 bits RSA) FS 256
- TLS_CHACHA20_POLY1305_SHA256 (0x1303) ECDH x25519 (eq. 3072 bits RSA) FS 256
- TLS_AES_128_GCM_SHA256 (0x1301) ECDH x25519 (eq. 3072 bits RSA) FS 128
TLS 1.2 (suites in server-preferred order)
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (0xc030) ECDH x25519 (eq. 3072 bits RSA) FS 256
- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (0xcca8) ECDH x25519 (eq. 3072 bits RSA) FS 256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (0xc02f) ECDH x25519 (eq. 3072 bits RSA) FS 128
A "Topic" represents a distinct outcome, business flow decision which can be uniquely identified. Topics will following a suffix versioning style such that the "topic" will be suffixed with a version number of the format v{n}, where n is a positive integer number >=1.
Example: "v1"
The topic naming convention is designed to help the receiving endpoint easily identity the following
The following are examples of topic names
checkprotect.transaction.approve.v1checkprotect.transaction.decline.v1checkprotect.transaction.manualreview.v1Ingo will always send a Webhook for every transaction request with the given Risk Score. If the transaction was sent to the Risk Center for manual review, we will also send a second Webhook after it has been reviewed with the updated score. Each payload will have a metadata and an eventData data section.
HTTP: POST
Content Type: application/json
| PARAMETER | REQ'T | TYPE | LEN | DESCRIPTION |
|---|---|---|---|---|
| metadata | RQD | OBJ | Information about the published webhook. | |
| webhookID | RQD | STR | 50 | A unique identifier for the given webhook in a guid. |
| topicName | RQD | STR | 255 | The specific event. |
| unixTimestamp | RQD | STR | 10 | Unix timestamp for the webhook request. |
| eventData | RQD | OBJ | Details on the update for the transaction | |
| requestId | RQD | STR | 50 | Ingo assigned identifier associated with the original request. |
| ingoCustomerId | RQD | STR | 50 | Ingo assigned customerID. |
| ingoTransactionId | RQD | STR | 50 | Ingo assigned TransactionID. |
| checkType | RQD | STR | 50 | Classification of check type. |
| checkMakerName | RQD | STR | 50 | Recognized maker of the check. |
| ingoCheckAmountInCents | RQD | INT | - | Amount of check in cents. |
| transactionRiskScore | RQD | INT | - | Ingo assigned risk score associated with check acceptance inclusive of configured overrides based upon a client's desired risk acceptance. |
| transactionRiskEngineScore | RQD | INT | - | Ingo assigned risk score associated with check acceptance. |
| clientData | RQD | OBJ | Information about the transaction subject to the update. | |
| clientId | RQD | STR | 50 | An echo of the Ingo assigned Client ID sent with the original request. |
| transactionId | RQD | STR | 50 | An echo of the unique client assigned transactionID sent with the original request. |
| customerId | RQD | STR | 50 | An echo of the unique client assigned customerID sent with the original request. |
{
"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": "67208089-e1d9-4f79-b41b-7be6ed5c21c1",
"webhookId": "ab45d8a2-98a6-4eed-9ac4-e151b640a435",
"unixTimestamp": 1638219167
}
}
Your webhook endpoint should return a 2xx HTTP response for success. Any other response will be viewed as a failure and Ingo Money will retry posting of the webhook by default every 30 mins for the next 24 hours.
Acceptance of webhook events should be independent of a client's ability to process webhooks downstream in support of internal processes. In the event of internal processing failure, prior acceptance of webhook events will allow a client to re-process these events without dependancy upon Ingo to replay events beyond the configured retry posting configuration.
Retry posting frequency, intervals and max attempts are configurable by endpoint. To prevent duplicate posting of an event, you should make your processing idempotent based on the webhookId value within the webhook metadata object.
When providing advance notice, Ingo can support maintenance windows which may impact a client's ability to accept webhook events. Please contact your assigned account coordinator for details.