Webhook events and subscriptions

What type of webhook events do we support and how do you subscribe to these events.

Suggest Edits

For an overview, see Webhooks. ▶ Run in Postman

To be sent an event notification you need to subscribe to the required event. You can subscribe to more than one event.

For example, subscribing to kyc.verification.success enables you to receive the successful result of a customer KYC verification request once it has finished being processed.

Event types

The following table lists the events that you can subscribe to.

Event enum valuesDescription
account.history.readyUsed when retrieving an external account history for the first time.
account.statements.readyMonthly statement for a credit or deposit account is now ready.
card.createdCard has been created.
card.status.activeCard status is now Active.
card.status.closedCard status is now Closed.
card.status.inactiveCard status is now Inactive.
card.status.reissueCard status is now Reissue.
card.wallet.addCard was successfully added to a mobile wallet.
card.wallet.add_failureCard failed to be added to a mobile wallet.
credit.application.createdThe credit application has been created.
credit.application.submittedCredit application has been submitted.
credit.application.approvedCredit application has been approved.
credit.application.adverse_actionA credit application adverse action has been generated.
credit.application.resubmit_requiredFor a secured charge account, the credit application KYC has failed or timed out. The application needs to be resubmitted with the same application_id.
kyb.verification.approvedKYB passed.
kyb.verification.errorKYB failed due to server error.
kyb.verification.initiatedKYB process has been initiated.
kyb.verification.rejectedKYB failed due to low confidence in identity validation.
kyb.verification.warningRun KYB again.
kyc.verification.document_requiredKYC requires further information to continue. This includes a documents field that indicates the types of documents required.
kyc.verification.errorKYC failed due to server error.
kyc.verification.failureKYC failed due to low confidence in identity validation.
kyc.verification.reenter_informationThis is optional and will be sent at the same time as kyc.verification.document_required.

The customer may have entered incorrect information that can cause KY failure. Reentering this information may resolve the issue. This includes an incorrect_information field that identifies exactly what should be checked by the customer.
kyc.verification.successKYC passed.
kyc.verification.timeoutThe system timed out trying to verify the information. Run KYC again.
kyc.verification.under_reviewKYC documents submitted are being reviewed.
transactionsSent on every new transaction or transaction update.

Webhook Configuration Example

curl --request POST \
     --url https://sandbox.bond.tech/api/v0.1/webhooks \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Content-Type: application/json' \
     --header 'Identity: YOUR-IDENTITY' \
     --data '
{
     "events": [
          "card.*",
          "credit.*",
          "kyc.*",
          "account.statement.ready",
          "transactions"
     ],
     "url": "https://hostname.com/webhook/route",
     "description": "KYC state changes."
}
'

📘

Note

You can also use wildcards when managing webhooks. For example, to refer to all card webhooks, use card*.

The following is an example of a successful 200 response which indicates that the subscription is enabled.

{
  "date_created": "2020-11-17T11:13:06.568119",
  "webhook_id": "522e9ec7-b17d-4d92-8270-c2e1741dd6e0",
  "url": "https://hostname.com/webhook/route",
  "description": "KYC state changes.",
  "events": [
        "card.created",
        "card.status.active",
        "card.status.closed",
        "card.status.fraud",
        "card.status.inactive",
        "card.status.lost",
        "card.status.no_withdrawals",
        "card.status.reissue",
        "card.status.stolen",
        "card.wallet.add",
        "card.wallet.add_failure",
        "credit.application.created",
        "credit.application.submitted",
        "credit.application.approved",
        "credit.application.adverse_action",
        "credit.application.resubmit_required",
        "kyc.verification.document_required",
        "kyc.verification.error",
        "kyc.verification.failure",
        "kyc.verification.reenter_information",
        "kyc.verification.success",
        "kyc.verification.timeout",
        "kyc.verification.under_review",
        "account.statement.ready",
        "transactions"
  ],
  "status": "STATUS_ENABLED",
  "secret": "whsec_XqTEJtniwuEhp0A1c1cTJNsmpR/qgOfB"
}

For a complete specification and interactive examples, see Managing subscriptions in the Bond API Reference.

Transaction event example

The transaction event example shown below sends notifications of every transaction type across card transactions, in addition to the ACH, and RCD transactions to the call-back URL provided. 

{
  "event": "transactions",
  "occurred_at": "2022-07-27T21:56:53.150700+00:00",
  "transaction": {
    "bond_brand_id": "48cd01ee-d333-4688-a6f4-fa1e9f12098b",
    "transaction_type": "ACH Deposit",
    "balances": null,
    "transaction_id": "d7990a22-ed1a-441a-b20a-c08307cce65b",
    "created_time": "2022-07-27T21:56:53.029766",
    "description": "Retest ACH Transactions",
    "amount": "10.01",
    "business_id": null,
    "account_id": "bc905964-1432-47f9-8cc5-b42a972bac32",
    "fee": null,
    "payment_type": "ach",
    "details": {
      "destination_account_id": "afeedb84-6b29-43d6-943f-8d221c7a795f",
      "originating_account_id": "10b55efe-fe7b-44de-9e21-5f7ce37d035e"
    },
    "customer_id": "e6cfcaea-195c-4fa7-a185-018118c38752",
    "currency": "USD",
    "updated_time": "2022-08-11T21:56:52.888542",
    "state": "pending",
    "previous_transaction_id": null
  }
}

Updated 3 months ago

Next Steps