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.

⚠️ Webhook Reliability and Deactivation

Trustpair requires your webhook endpoint to return a 200 HTTP status code for every webhook event, regardless of how the vendor check was initiated.

🔁 Applies to All Vendor Checks

Webhooks are scoped by module, not by creation source. This means you will receive webhook notifications even for vendor checks not created via the API, such as those created manually in the Trustpair web platform.

❗ Common Mistake: Some clients only return a 200 OK for checks they created via the API. This leads to Trustpair retrying and eventually deactivating the webhook because unacknowledged events (e.g., from the UI) are treated as failures.

🔄 Retry & Deactivation Policy

If a webhook does not receive a 200 response:

Trustpair will retry the same event up to 10 times over a 4-hour window.
If no successful response is received after all retries, Trustpair stops retrying the event but will keep trying to deliver the next events.

✅ Best Practice

Always respond with a 200 OK to any valid webhook request, regardless of:

The origin of the check (API, manual, etc.)
Whether you actively process the payload

If needed, defer processing internally but ensure the response is sent promptly to maintain webhook availability.

🔐
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