Webhooks at Trustpair
Trustpair uses webhooks to notify your application when there's a change in the status of a third-party. For instance, Trustpair will send a POST request to the URL of your choice whenever a third-party goes from a "Pending" state to a "Favorable" state.
Webhooks are particularly helpful, since in some cases, the evaluation from Trustpair may be asynchronous, especially in the case of complementary checks. This prevents you from having to set up recurring GET requests to retrieve the payload and figure out if the state in the payload has changed.
Trustpair's webhooks are scoped to each module of your Trustpair's application. This means that a given webhook should be configured for one of the three endpoints below:
- account_check
- account_audit
- payment_check
You can set-up as many webhooks as you want
Bear in mind that you will have to create one webhook for each module you want to trigger events from
For each status change, Trustpair will send a POST request to the URL of your choice in JSON format. This API call contains an object. The object will depend on the Module on which you have decided to trigger the webhook. The object looks exactly like the respective objects you retrieve when you perform GET requests via the API on each module.
Ex: for Module 1, after a change of status, Trustpair will send the following object to the URL you configured :
{
"data": {
"id": "1926c774-b6b7-4417-ae85-d88c9c7be92b",
"type": "company_account_check",
"attributes": {
"company_country_code": "FR",
"company_country_code_iso3": "FRA",
"company_registration": "832940670",
"tax_number": null,
"duns": null,
"company_details": {
"name": "Trustpair",
"commercial_name": "Trustpair",
"address": {
"street": "174 Quai de Jemmapes",
"city": "Paris",
"state": "Paris",
"country": "France",
"country_code": "FR",
"zip_code": "75010"
},
"employees": "10 à 19 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": "FR7600009999999999990123456",
"bank_account_country_code": "FR",
"bank_account_country_code_iso3": "FRA",
"bank_account_number": null,
"bank_account_bic": "BARBGB2LKEN",
"routing_number": null,
"control_key": null,
"bank_details": {
"account_blacklisted": false,
"factor": false,
"name": "ALKEN ASSET MANAGEMENT",
"address": {
"street": "174 Quai de Jemmapes",
"city": "Paris",
"state": "Paris",
"country": "France",
"country_code": "FR",
"zip_code": "75010"
}
},
"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": [
"external_source_favorable"
],
"state": "favorable",
"state_reasons": [
"The bank account belongs to the supplier"
]
}
},
"requested_at": 1614869804,
"requested_via_api": true,
"first_name": null,
"last_name": null,
"middle_name": null,
"other_name": null,
"birthdate": null,
"natural_person_country_code": null,
"natural_person_country_code_iso3": null,
"natural_person_tax_number": null
}
}
}
Verifying webhooks signatures
Webhooks sent by Trustpair are signed. Verifying the signature helps ensure the authenticity and integrity of webhook payloads sent by Trustpair. More on that in this section: Webhooks signatures