Prime Trust Webhooks Integration

Webhooks are the best way of receiving updates on resource information from our system (unnecessary pulling of the API can lead to rate limiting). Webhooks sent all have similar structures, and notify the integrator when a resource needs to be pulled from our API to get updated information regarding account openings, contact KYC, funds/assets moving, etc.

Following is an example of a webhook sent on a contact that has an exception raised on their KYC process that's been updated on the cip_checks resource. Following this webhook, you would make a GET call to /v2/cip-checks/acea9ab2-e9f6-4541-96a4-c9247019b7e4 to see what the updated value on the key exceptions is.

{"id": "ab2f5c9f-203a-4212-aee1-72070f5abe45", (Webhook ID)
"account-id": "73e5360f-012f-4ac9-8908-770060733ca4", (Associated AccountID)
"action": "update", (Update or Create)
"data": {
"changes": [
"exceptions"
]
}, (Changes Array shows what Keys have had changed Values)
"resource-id": "acea9ab2-e9f6-4541-96a4-c9247019b7e4", (ID of the Resource)
"resource-type": "cip_checks", (Resource Type)
"account_id": "73e5360f-012f-4ac9-8908-770060733ca4", (Associated AccountID)
"resource_id": "acea9ab2-e9f6-4541-96a4-c9247019b7e4",
"resource_type": "cip_checks"}
note

Webhook testing can be done in sandbox for almost every aspect except generating exceptions on contact details. To test these, ask your Sales Engineer to throw an exception for a contact by giving them a contact-id that is currently in the status of pending. Your Sales Engineer can simulate automated check failures for cip-checks(Exceptions), and also simulate custom notes that our compliance department might attach to the particular contact(Exception-Details).

Handling webhooks

Your integration should be able to handle webhooks for, at minimum, the following resource-types:

  • account-cash-transfers

  • accounts

  • aml-checks

  • cip-checks

  • contacts

  • contingent-holds

  • disbursement-authorizations

  • funds-transfers (asset-transfers also if we are custodying assets)

note

This list is subject to change as new features are added to the API.

Webhook examples

Below we’ll list some more common examples of when webhooks are sent. There is no exhaustive list, and what webhooks are used can differ from integrator to integrator. It is highly encouraged that you implement and test your webhooks in the sandbox environment.

ResourceChangesDescription
Account"Status"Fired when an account goes from “pending” to “open” (can signify contact passing KYC and capability for funds movement).
Contact
  • "Cip-Cleared"
  • "Aml-Cleared"
  • "Identity-Confirmed"
Fired when KYC checks for a contact have been completed (Cip-Cleared + Aml-Cleared = Identity-Confirmed). Aml Checks are also done on all incoming and outgoing funds/assets, and a webhook will be fired when that aml check is cleared.
Cip-Checks
  • "Exceptions"
  • "Exception-Details"
Fired when KYC checks on PII for contacts have an issue being passed.
KYC-Document-Checks"Exceptions"
Funds-TransferLots of fields here can be updated for different properties on a transfer of funds. The more common fields to look at would be "amount", "status", "clears-on", "contingencies-cleared-on", "canceled-at", "reversal-details".
Plaid-ItemsYou should receive a Webhook when a Plaid Link is established and a Funds-Transfer-Method is created. You will also receive a webhook if a Plaid linking is broken (end-user changed bank login info) and when a Plaid link is re-established.
Contingent-Hold
  • "Cleared-At"
  • "Status"
Fired when a Contingent-Hold is cleared(there are usually multiple contingent-holds to clear).
Refund
Account-Cash-Transfer
  • "Status"
  • "From-cash-transaction"
  • "To-cash-transaction"
Fired when an Internal Transfer is initiated (and instantly settled).
Disbursement-Authorizations
  • "Owner-Verified-At"
  • "Status"
Fired when an end-user has clicked their disbursement-authorization link in their email.
Asset-TransfersFields to focus on:
  • "status"
  • "unit-count"
Last updated on