Trustpair uses webhooks to automatically notify your application when the status of a vendor check changes. For example, when a check transitions from "Pending" to "Favorable".
Some Trustpair evaluations are asynchronous, particularly when additional checks are involved. Rather than polling the API with repeated GET requests, webhooks allow your application to react instantly when something changes.
✅ Why Use Webhooks?
By using webhooks, you:
- Reduce API overhead
- Receive real-time updates
- Improve reliability and responsiveness
🔗 Module-Specific Webhooks
Trustpair’s webhooks are scoped by module. This means each webhook is associated with one specific type of check:
- company_account_checks (Module 1 - Control)
- company_account_audits (Module 2 - Audit)
- payment_checks (Module 3 - Payment)
You must set up a separate webhook for each module you want to listen to.
🔄 How It Works
Whenever a relevant status changes, Trustpair sends a POST request to the webhook URL configured. The request body contains a JSON object representing the updated resource.
🔧 Example
If you’re listening for updates on the company_account_checks endpoint, and a vendor check's status changes, Trustpair will send a POST request like this:
{
"id":"d6200519-1744-493f-b8ec-11d94e3fb160",
"type":"company_account_check",
"attributes":{
"company_name":null,
"company_country_code":"FR",
"company_country_code_iso3":"FRA",
"company_registration":"832940670",
"tax_number":null,
"duns":null,
"company_details":{
"name":"TRUSTPAIR",
"commercial_name":null,
"address":{
"street":"174 Quai de Jemmapes",
"city":"Paris",
"state":"Île-de-France",
"country":"France",
"country_code":"FR",
"zip_code":"75010"
},
"employees":"50 à 99 salariés",
"legal_form":"SAS, société par actions simplifiée",
"opening_date":1569888000,
"dissolution_date":null,
"activity":{
"code":"62.01Z",
"label":"Programmation, conseil et autres activités informatiques",
"type":"ape"
},
"insolvencies":[
]
},
"iban":null,
"bank_account_country_code":"US",
"bank_account_country_code_iso3":"USA",
"bank_account_number":"3303486083",
"bank_account_bic":"FCBTUS33XXX",
"routing_number":"121140399",
"control_key":null,
"bank_details":{
"account_blacklisted":false,
"factor":false,
"name":"First-Citizens Bank and Trust Company",
"address":{
"street":"100 E Tryon Rd",
"city":"Raleigh",
"state":"North Carolina",
"country":"United States",
"country_code":"US",
"zip_code":"27603"
}
},
"state":"favorable",
"state_reasons":{
"company":{
"raw":[
"supplier_default_favorable"
],
"state":"favorable",
"state_reasons":[
"The company is active"
]
},
"bank_account":{
"raw":[
"bank_account_default_favorable"
],
"state":"favorable",
"state_reasons":[
"The bank account is valid"
]
},
"correlation":{
"raw":[
"kys_favorable"
],
"state":"favorable",
"state_reasons":[
"The bank account belongs to the supplier"
]
}
},
"requested_at":1751291780,
"requested_via_api":false,
"first_name":null,
"last_name":null,
"other_name":null,
"birthdate":null,
"middle_name":null,
"natural_person_country_code":null,
"natural_person_country_code_iso3":null,
"natural_person_tax_number":null,
"override_initial_status":null,
"override_request_date":null,
"override_request_initiator":null,
"override_review_date":null,
"override_request_reviewer":null
}
}
🚀 Next Steps
- Choose the modules you want to monitor.
- Configure your webhook URLs with the help of your Customer Success Manager.
- Implement webhook receivers in your application to handle the payloads.
- Secure your endpoint and validate payload authenticity.
Verifying Webhooks Signatures
Webhooks sent by Trustpair are signed to ensure their authenticity.
Verifying the signature allows your server to:
- Confirm the request is actually from Trustpair
- Detect any tampering with the payload
- Prevent replay attacks
🔗 Learn how to verify signatures here: Verifying Webhook Signatures from Trustpair