Token Sharing Webhooks
Get notified when tokens are sent, imported or fail to import.
AiPrise sends a webhook when a token moves through the import steps.
Events
| Event | Sent when | Recipient | Donor |
|---|---|---|---|
TOKEN_READY_TO_BE_IMPORTED | A token has been sent to the Recipient | Yes | No |
TOKEN_IMPORTED | The Recipient's copy has been created | Yes | Yes |
TOKEN_IMPORT_FAILED | The import could not complete | Yes | Yes, reason code only |
Webhook URLs are set on the agreement. The Recipient sets its URL in the agreement's Recipient configuration. Contact the AiPrise team to set the Donor's URL.
Payload
Every webhook carries the event type and the token, as the receiving side sees it. See The token object.
{
"token_sharing_event_type": "TOKEN_IMPORTED",
"token": {
"id": "3f6d2c1a-8b4e-4f0a-9c7d-2e5b1a9f0c44",
"donor_company_id": "1d2c3b4a-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"recipient_company_id": "7e1f0a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
"contract_id": "c1a2b3c4-d5e6-4f70-8a91-b2c3d4e5f607",
"agreement_id": "a9b8c7d6-e5f4-4321-9876-0fedcba98765",
"agreement_version": 2,
"entity_type": "BUSINESS_PROFILE",
"entity_name_as_per_donor": "Acme Pte Ltd",
"state": "IMPORTED",
"entity_id_as_per_recipient": "9c8b7a6f-5e4d-4c3b-a2f1-0e9d8c7b6a5f",
"created_at": 1795100000000,
"updated_at": 1795100004000
}
}TOKEN_IMPORT_FAILED also includes a failure object. The Recipient gets the reason and details. The Donor gets the reason only.
{
"token_sharing_event_type": "TOKEN_IMPORT_FAILED",
"token": {
"id": "3f6d2c1a-8b4e-4f0a-9c7d-2e5b1a9f0c44",
"donor_company_id": "1d2c3b4a-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"recipient_company_id": "7e1f0a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
"contract_id": "c1a2b3c4-d5e6-4f70-8a91-b2c3d4e5f607",
"agreement_id": "a9b8c7d6-e5f4-4321-9876-0fedcba98765",
"agreement_version": 2,
"entity_type": "BUSINESS_PROFILE",
"entity_name_as_per_donor": "Acme Pte Ltd",
"state": "IMPORT_FAILED",
"entity_id_as_per_recipient": null,
"created_at": 1795100000000,
"updated_at": 1795100004000
},
"failure": {
"reason": "MISSING_INPUTS",
"details": "<what was missing>"
}
}See Handle a failed import for the list of reasons.
Delivery
- Webhooks are signed with the
X-HMAC-SIGNATUREheader, the same as other AiPrise callbacks. See Callback Authentication. - Each webhook is delivered on its own, and the order is not guaranteed. With automatic import,
TOKEN_READY_TO_BE_IMPORTEDandTOKEN_IMPORTEDare sent back to back and can arrive in either order. Always readtoken.staterather than relying on the order of arrival. - If you miss a webhook, use List received tokens or List exported tokens to catch up.
Updated about 20 hours ago
Did this page help you?
