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

EventSent whenRecipientDonor
TOKEN_READY_TO_BE_IMPORTEDA token has been sent to the RecipientYesNo
TOKEN_IMPORTEDThe Recipient's copy has been createdYesYes
TOKEN_IMPORT_FAILEDThe import could not completeYesYes, 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-SIGNATURE header, 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_IMPORTED and TOKEN_IMPORTED are sent back to back and can arrive in either order. Always read token.state rather than relying on the order of arrival.
  • If you miss a webhook, use List received tokens or List exported tokens to catch up.

Did this page help you?