Guides

Webhooks

Suggest Edits

Webhooks enable apps to provide real-time information whenever an event happens without needing constant requests. They are the best way to ensure your system is up-to-date with payment progress and status. After configuring BoomFi's Webhooks, you will receive event notifications automatically every time an activity or a function is generated within our flow.

Webhook types

Our system has three distinct types of webhooks: Plan, Subscription, Payment, and Invoice. Each type serves a unique purpose in our webhook architecture. Below, you will find more about each type.

Plan webhooks

Plans are objects created when your team creates a new payment plan.

One-time plan created

This webhook for a One-Time plan type is triggered by the event Plan.Created and is designed to send you a notification when a one-time plan is created. An example of this webhook is presented as follows:

{
  "id": "2U4PAgjORxLTtqWCJjyGUjMKUTS",
  "org_id": "2U1BReVO7RxSPbhCdGtCBHEah6r",
  "name": "ZenBlend Aromatherapy Diffuser",
  "description": "Enhance ambiance: diffuse calming mists and LED serenity.",
  "type": "OneTime",
  "billing_scheme": "FlatFee",
  "price": "29.99",
  "currency": "USD",
  "available_quantity": 100,
  "reference": "23c5aa2d-65b3-42a8-a517-26e8a1e732c6",
  "metadata": {},
  "enabled": true,
  "created_by": "2U1BRhqKBt5WToGSRvXYrmwESuZ",
  "created_at": "2023-08-16T14:22:16.908838Z",
  "updated_at": "2023-08-16T14:22:17.473089941Z",
  "source": "BoomFi",
  "event": "Plan.Created"
}

Recurring plan created

This webhook for a Recurring plan type is also triggered by the event Plan.Created and will send you a notification when a recurring plan is created. An example of this webhook is presented below:

{
  "id": "2U4QqobIMPgsdiudz9up5C8t8he",
  "org_id": "2U1BReVO7RxSPbhCdGtCBHEah6r",
  "name": "ACME Premium Plan",
  "description": "ACME Premium Plan: Elevate your experience with exclusive benefits.",
  "type": "Recurring",
  "billing_scheme": "FlatFee",
  "price": "69.99",
  "currency": "USD",
  "available_quantity": 0,
  "trial_period": "",
  "recurring_interval": "Year",
  "recurring_interval_count": 1,
  "recurring_usage_type": "Unknown",
  "reference": "0d8cc65f-ea3a-4f32-89ea-8b8e7ceaf028",
  "metadata": {},
  "enabled": true,
  "created_by": "2U1BRhqKBt5WToGSRvXYrmwESuZ",
  "created_at": "2023-08-16T14:36:04.943379Z",
  "updated_at": "2023-08-16T14:36:05.514017739Z",
  "source": "BoomFi",
  "event": "Plan.Created"
}

Plan update enabled

You will receive notifications when the plan is updated. An example of this webhook is presented in the following code block:

{
  "id": "2U75Xjokx2lchimqSnpctVya8B3",
  "org_id": "2U1BReVO7RxSPbhCdGtCBHEah6r",
  "name": "ACME Premium Plan",
  "description": "ACME Premium Plan: Elevate your experience with exclusive benefits.",
  "type": "Recurring",
  "billing_scheme": "FlatFee",
  "price": "109.99",
  "currency": "USD",
  "available_quantity": 0,
  "trial_period": "",
  "recurring_interval": "Week",
  "recurring_interval_count": 1,
  "recurring_usage_type": "Unknown",
  "reference": "94efdb81-d1af-4d51-829f-76021eea71c5",
  "metadata": {},
  "enabled": false,
  "created_by": "2U1BRhqKBt5WToGSRvXYrmwESuZ",
  "created_at": "2023-08-17T13:10:18.880611Z",
  "updated_at": "2023-08-17T13:11:29.617297516Z",
  "source": "BoomFi",
  "event": "Plan.Updated"
}

Plan update disabled

A Plan or related payment link deactivated by the user. An example of this webhook is presented in the following code block:

{
  "id": "2U75Xjokx2lchimqSnpctVya8B3",
  "org_id": "2U1BReVO7RxSPbhCdGtCBHEah6r",
  "name": "ACME Premium Plan",
  "description": "ACME Premium Plan: Elevate your experience with exclusive benefits.",
  "type": "Recurring",
  "billing_scheme": "FlatFee",
  "price": "109.99",
  "currency": "USD",
  "available_quantity": 0,
  "trial_period": "",
  "recurring_interval": "Week",
  "recurring_interval_count": 1,
  "recurring_usage_type": "Unknown",
  "reference": "94efdb81-d1af-4d51-829f-76021eea71c5",
  "metadata": {},
  "enabled": false,
  "created_by": "2U1BRhqKBt5WToGSRvXYrmwESuZ",
  "created_at": "2023-08-17T13:10:18.880611Z",
  "updated_at": "2023-08-17T13:11:29.617297516Z",
  "source": "BoomFi",
  "event": "Plan.Updated"
}

Subscription webhooks

Subscriptions are objects created when a customer subscribes to one of your recurring payment plans.

Subscription created

This webhook sends you a notification when a subscription is created in your merchant account. An example of this webhook is presented as follows:

{
  "id": "2U4R7PnqLsyhoExzSb7tUskjztn",
  "customer_id": "2U4NjdOjTAa5aNyuyRzl8ZVoKXB",
  "created_at": "2023-08-16T14:38:18.93852199Z",
  "updated_at": "2023-08-16T14:38:18.981702389Z",
  "status": "Pending",
  "cancel_at_period_end": false,
  "metadata": {},
  "reference": "product-code-123",
  "currency": "",
  "customer": {
    "id": "2VyNhwVqrTj8aU6D6n5zldQgskJ",
    "created_at": "2023-09-27T08:48:02.381Z",
    "updated_at": "2023-10-15T13:57:51.736Z",
    "org_id": "2UAYLS2O7VDpJbREZkIfQt035Jl",
    "metadata": {},
    "reference": "awesome-user-123",
    "deleted_at": {
      "Time": "0001-01-01T00:00:00Z",
      "Valid": false
    },
    "email": "[email protected]",
    "name": "Alchemy growth",
    "phone": "2441234567",
    "wallet_address": "0x62cb57395eac2666F6218a514c895dd7049d9d9b"
  },
  "source": "BoomFi",
  "event": "Subscription.Created"
}

Subscription updated - active

This webhook updates you when a subscription is active so that you can share it with customers. An example of this webhook is presented in the following code block:

{
  "id": "2U4R7PnqLsyhoExzSb7tUskjztn",
  "customer_id": "2U4NjdOjTAa5aNyuyRzl8ZVoKXB",
  "created_at": "2023-08-16T14:38:28.665289Z",
  "updated_at": "2023-08-16T14:38:28.903426957Z",
  "status": "Active",
  "cancel_at_period_end": false,
  "metadata": {},
  "reference": "product-code-123",
  "currency": "",
  "customer": {
    "id": "2VyNhwVqrTj8aU6D6n5zldQgskJ",
    "created_at": "2023-09-27T08:48:02.381Z",
    "updated_at": "2023-10-15T13:57:51.736Z",
    "org_id": "2UAYLS2O7VDpJbREZkIfQt035Jl",
    "metadata": {},
    "reference": "awesome-user-123",
    "deleted_at": {
      "Time": "0001-01-01T00:00:00Z",
      "Valid": false
    },
    "email": "[email protected]",
    "name": "Alchemy growth",
    "phone": "2441234567",
    "wallet_address": "0x62cb57395eac2666F6218a514c895dd7049d9d9b"
  },
  "source": "BoomFi",
  "event": "Subscription.Updated"
}

Subscription updated - succeeded

This webhook sends you a notification when a customer subscription is active. An example of this webhook is presented as follows:

{
  "id": "2ULboTTT4w2chedUQyiRXpk2YM7",
  "customer_id": "2U8OOGnTgtKrMqHVHIRh436yLnR",
  "created_at": "2023-08-22T16:33:10.61684Z",
  "updated_at": "2023-08-22T16:33:10.910130633Z",
  "status": "Active",
  "cancel_at_period_end": false,
  "metadata": {},
  "reference": "product-code-123",
  "currency": "",
  "customer": {
    "id": "2VyNhwVqrTj8aU6D6n5zldQgskJ",
    "created_at": "2023-09-27T08:48:02.381Z",
    "updated_at": "2023-10-15T13:57:51.736Z",
    "org_id": "2UAYLS2O7VDpJbREZkIfQt035Jl",
    "metadata": {},
    "reference": "awesome-user-123",
    "deleted_at": {
      "Time": "0001-01-01T00:00:00Z",
      "Valid": false
    },
    "email": "[email protected]",
    "name": "Alchemy growth",
    "phone": "2441234567",
    "wallet_address": "0x62cb57395eac2666F6218a514c895dd7049d9d9b"
  },
  "source": "Lago",
  "event": "Subscription.Updated"
}

Subscription updated - canceled

With this webhook, you can get to know when a customer cancels a subscription, thus you can quickly take actions to reduce churn. An example of this webhook is presented in the following code block:

{
  "id": "2U4R7PnqLsyhoExzSb7tUskjztn",
  "customer_id": "2U4NjdOjTAa5aNyuyRzl8ZVoKXB",
  "created_at": "2023-08-16T14:38:28.665289Z",
  "updated_at": "2023-08-16T14:39:58.905858958Z",
  "status": "Canceled",
  "cancel_at_period_end": false,
  "metadata": {},
  "reference": "product-code-123",
  "currency": "",
  "customer": {
    "id": "2VyNhwVqrTj8aU6D6n5zldQgskJ",
    "created_at": "2023-09-27T08:48:02.381Z",
    "updated_at": "2023-10-15T13:57:51.736Z",
    "org_id": "2UAYLS2O7VDpJbREZkIfQt035Jl",
    "metadata": {},
    "reference": "awesome-user-123",
    "deleted_at": {
      "Time": "0001-01-01T00:00:00Z",
      "Valid": false
    },
    "email": "[email protected]",
    "name": "Alchemy growth",
    "phone": "2441234567",
    "wallet_address": "0x62cb57395eac2666F6218a514c895dd7049d9d9b"
  },
  "source": "BoomFi",
  "event": "Subscription.Canceled"
}

Payment webhooks

Payment created

This webhook sends you a notification when a payment is created. An example of this webhook is presented as follows:

{
    "id": "2U7H5zYPtWl30MyCxtpbFwGSLGZ",
    "amount": "69.99",
    "created_at": "2023-08-16T14:38:18.671976Z",
    "customer_id": "2U4NjdOjTAa5aNyuyRzl8ZVoKXB",
    "status": "Processing",
    "updated_at": "2023-08-16T14:38:36.690290504Z",
    "payment_method": "Crypto",
    "plan": {
      "id": "plan_2dsanFpZWEG2mhYyhmv50hMz7Zm",
      "reference": "db0ad3c4-3ffc-49bc-8ff3-377ef511a70b"
    },
    "currency": "USDC",
    "invoice_id": "",
    "next_action": "",
    "crypto_transaction": {
      "hash": "0x451f68bb3b3d44db8005be9023f3db177268970167351e7e1ac9678f99d1d403",
      "chain_id": 1
    },
    "customer": {
      "id": "2VyNhwVqrTj8aU6D6n5zldQgskJ",
      "created_at": "2023-09-27T08:48:02.381Z",
      "updated_at": "2023-10-15T13:52:46.166Z",
      "org_id": "2UAYLS2O7VDpJbREZkIfQt035Jl",
      "metadata": {},
      "reference": "",
      "email": "[email protected]",
      "name": "Alchemy growth",
      "phone": "2441234567",
      "wallet_address": "0x62cb57395eac2666F6218a514c895dd7049d9d9b"
    },
    "event": "Payment.Created"
  }

Payment update - in process

This webhook sends you a notification when a payment for a subscription plan or one-time pay link is in process. An example of this webhook is presented below:

{
    "id": "2U7H5zYPtWl30MyCxtpbFwGSLGZ",
    "amount": "69.99",
    "created_at": "2023-08-17T14:45:17.754623Z",
    "customer_id": "2U4NjdOjTAa5aNyuyRzl8ZVoKXB",
    "status": "Processing",
    "updated_at": "2023-08-17T14:45:21.413604986Z",
    "payment_method": "Crypto",
    "plan": {
      "id": "plan_2dsanFpZWEG2mhYyhmv50hMz7Zm",
      "reference": "db0ad3c4-3ffc-49bc-8ff3-377ef511a70b"
    },
    "currency": "USDC",
    "invoice_id": "",
    "next_action": "",
    "crypto_transaction": {
      "hash": "0x451f68bb3b3d44db8005be9023f3db177268970167351e7e1ac9678f99d1d403",
      "chain_id": 1
    },
    "customer": {
      "id": "2VyNhwVqrTj8aU6D6n5zldQgskJ",
      "created_at": "2023-09-27T08:48:02.381Z",
      "updated_at": "2023-10-15T13:52:46.166Z",
      "org_id": "2UAYLS2O7VDpJbREZkIfQt035Jl",
      "metadata": {},
      "reference": "",
      "email": "[email protected]",
      "name": "Alchemy growth",
      "phone": "2441234567",
      "wallet_address": "0x62cb57395eac2666F6218a514c895dd7049d9d9b"
    },
    "event": "Payment.Updated"
  }

Payment update - succeeded

This webhook sends you a notification when a payment is successfully completed by the customer. An example of this webhook is presented as follows:

{
    "id": "2U7H5zYPtWl30MyCxtpbFwGSLGZ",
    "amount": "69.99",
    "created_at": "2023-08-17T14:45:17.754623Z",
    "customer_id": "2U4NjdOjTAa5aNyuyRzl8ZVoKXB",
    "status": "Succeeded",
    "updated_at": "2023-08-17T14:45:27.585755671Z",
    "payment_method": "Crypto",
    "plan": {
      "id": "plan_2dsanFpZWEG2mhYyhmv50hMz7Zm",
      "reference": "db0ad3c4-3ffc-49bc-8ff3-377ef511a70b"
    },
    "currency": "USDC",
    "invoice_id": "",
    "next_action": "",
    "crypto_transaction": {
      "hash": "0x451f68bb3b3d44db8005be9023f3db177268970167351e7e1ac9678f99d1d403",
      "chain_id": 1
    },
    "customer": {
      "id": "2VyNhwVqrTj8aU6D6n5zldQgskJ",
      "created_at": "2023-09-27T08:48:02.381Z",
      "updated_at": "2023-10-15T13:52:46.166Z",
      "org_id": "2UAYLS2O7VDpJbREZkIfQt035Jl",
      "metadata": {},
      "reference": "",
      "email": "[email protected]",
      "name": "Alchemy growth",
      "phone": "2441234567",
      "wallet_address": "0x62cb57395eac2666F6218a514c895dd7049d9d9b"
    },
    "event": "Payment.Updated"
  }

Invoice webhooks

Invoices are objects created when a new invoice is generated.

Invoice created

This event will notify you when a new invoice is created. Every newly created invoice will have an unknown payment status.

{
  "id": "inv_2lbpkhlbqWBbo4cd11brz8Ij75L",
  "customer_id": "2jdZlAbfpxZSY80bx81AqwuWuje",
  "amount": "1",
  "currency": "USDC",
  "issuing_at": "2024-09-04T14:06:14.470799Z",
  "due_at": "2024-09-07T14:06:14.470799Z",
  "reference": "test_2lbpkd6vAL0kza0zKpmWLpKJ611_inv_2lbpkhlbqWBbo4cd11brz8Ij75L",
  "source": "BoomFi",
  "payment_status": "Unknown",
  "status": "Open",
  "dunning_status": "Unknown",
  "created_at": "2024-09-04T14:06:14.470799Z",
  "updated_at": "2024-09-04T14:06:14.470799Z",
  "invoice_items": [
    {
      "period_end_at": "2024-10-03T23:59:59Z",
      "period_start_at": "2024-09-04T14:06:14.471Z",
      "plan": {
        "id": "2lbpkf3whsDiGXm1ECfRiXgnrYf",
        "org_id": "2Yy8BjDAxETxNZjFqRn4WWYEVHx",
        "source": "BoomFi",
        "name": "Plan for test 2lbpkd6vAL0kza0zKpmWLpKJ611",
        "type": "Recurring",
        "billing_scheme": "FlatFee",
        "price": "1",
        "currency": "USDC",
        "available_quantity": 1,
        "trial_period": "",
        "recurring_interval": "Month",
        "recurring_interval_count": 0,
        "recurring_usage_type": "Licensed",
        "reference": "test_2lbpkd6vAL0kza0zKpmWLpKJ611_plan_2lbpkf3whsDiGXm1ECfRiXgnrYf",
        "metadata": "e30=",
        "enabled": true,
        "properties": "e30=",
        "v1": "e30=",
        "created_by": "2Yy8BcbicwelIy03hrdxaJcYe5A",
        "created_at": "2024-09-04T14:06:14.471Z",
        "updated_at": "2024-09-04T14:06:14.471Z",
        "deleted_at": null
      },
      "subscription": {
        "id": "2lbpkeRtjo0OhxLbU38sHs3AXpj",
        "org_id": "2Yy8BjDAxETxNZjFqRn4WWYEVHx",
        "customer_id": "2jdZlAbfpxZSY80bx81AqwuWuje",
        "source": "BoomFi",
        "currency": "USDC",
        "payment_method": "MerchantContract",
        "cancel_at_period_end": false,
        "start_at": "2024-09-04T14:06:14.471Z",
        "reference": "test_2lbpkd6vAL0kza0zKpmWLpKJ611_sub_2lbpkeRtjo0OhxLbU38sHs3AXpj",
        "metadata": "e30=",
        "status": "Active",
        "properties": "eyJjaGFpbl9pZCI6IDEsICJ0ZXN0X21vZGUiOiB0cnVlLCAibmV4dF9hdHRlbXB0IjogIjIwMjQtMDktMDVUMTQ6MDY6MTRaIn0=",
        "v1": "e30=",
        "created_at": "2024-09-04T14:06:14.471Z",
        "updated_at": "2024-09-04T14:06:14.471Z"
      }
    }
  ],
  "payment_link": {
    "id": "2lbpkgbrBw4tYxnjonCDUVnUrfg",
    "plan_id": "2lbpkf3whsDiGXm1ECfRiXgnrYf",
    "invoice_id": "2lbpkhlbqWBbo4cd11brz8Ij75L",
    "source": "BoomFi",
    "metadata": "e30=",
    "customer_ident_collection": false,
    "shipping_address_collection": false,
    "tax_ident_collection": false,
    "enabled": true,
    "deleted_at": null,
    "properties": "e30=",
    "created_by": "",
    "updated_by": "",
    "created_at": "2024-09-04T14:06:14.505Z",
    "updated_at": "2024-09-04T14:06:14.505Z"
  },
  "org_id": "2Yy8BjDAxETxNZjFqRn4WWYEVHx",
  "org": {
    "id": "org_2Yy8BjDAxETxNZjFqRn4WWYEVHx",
    "name": "TestMerchant2"
  },
  "customer": {
    "id": "cus_2jdZlAbfpxZSY80bx81AqwuWuje",
    "org_id": "2Yy8BjDAxETxNZjFqRn4WWYEVHx",
    "name": "Test",
    "email": "[email protected]",
    "phone": "",
    "wallet_address": "0xF6F97412a831047D62A3B394107911619cAF7559",
    "deleted_at": null,
    "reference": "",
    "metadata": {},
    "created_at": "2023-12-02T03:05:24.144Z",
    "updated_at": "2023-12-02T03:05:24.4Z"
  },
  "event": "Invoice.Created"
}

Invoice overdue

This webhook sends you a notification to alert you that the invoice is overdue.

{
  "id": "inv_2lbpkhlbqWBbo4cd11brz8Ij75L",
  "customer_id": "2jdZlAbfpxZSY80bx81AqwuWuje",
  "amount": "1",
  "currency": "USDC",
  "issuing_at": "2024-09-04T14:06:14.470799Z",
  "due_at": "2024-09-07T14:06:14.470799Z",
  "reference": "test_2lbpkd6vAL0kza0zKpmWLpKJ611_inv_2lbpkhlbqWBbo4cd11brz8Ij75L",
  "source": "BoomFi",
  "payment_status": "Failed",
  "status": "Open",
  "dunning_status": "InProgress",
  "created_at": "2024-09-04T14:06:14.470799Z",
  "updated_at": "2024-09-04T14:06:14.470799Z",
  "invoice_items": [
    {
      "period_end_at": "2024-10-03T23:59:59Z",
      "period_start_at": "2024-09-04T14:06:14.471Z",
      "plan": {
        "id": "2lbpkf3whsDiGXm1ECfRiXgnrYf",
        "org_id": "2Yy8BjDAxETxNZjFqRn4WWYEVHx",
        "source": "BoomFi",
        "name": "Plan for test 2lbpkd6vAL0kza0zKpmWLpKJ611",
        "type": "Recurring",
        "billing_scheme": "FlatFee",
        "price": "1",
        "currency": "USDC",
        "available_quantity": 1,
        "trial_period": "",
        "recurring_interval": "Month",
        "recurring_interval_count": 0,
        "recurring_usage_type": "Licensed",
        "reference": "test_2lbpkd6vAL0kza0zKpmWLpKJ611_plan_2lbpkf3whsDiGXm1ECfRiXgnrYf",
        "metadata": "e30=",
        "enabled": true,
        "properties": "e30=",
        "v1": "e30=",
        "created_by": "2Yy8BcbicwelIy03hrdxaJcYe5A",
        "created_at": "2024-09-04T14:06:14.471Z",
        "updated_at": "2024-09-04T14:06:14.471Z",
        "deleted_at": null
      },
      "subscription": {
        "id": "2lbpkeRtjo0OhxLbU38sHs3AXpj",
        "org_id": "2Yy8BjDAxETxNZjFqRn4WWYEVHx",
        "customer_id": "2jdZlAbfpxZSY80bx81AqwuWuje",
        "source": "BoomFi",
        "currency": "USDC",
        "payment_method": "MerchantContract",
        "cancel_at_period_end": false,
        "start_at": "2024-09-04T14:06:14.471Z",
        "reference": "test_2lbpkd6vAL0kza0zKpmWLpKJ611_sub_2lbpkeRtjo0OhxLbU38sHs3AXpj",
        "metadata": "e30=",
        "status": "Active",
        "properties": "eyJjaGFpbl9pZCI6IDEsICJ0ZXN0X21vZGUiOiB0cnVlLCAibmV4dF9hdHRlbXB0IjogIjIwMjQtMDktMDVUMTQ6MDY6MTRaIn0=",
        "v1": "e30=",
        "created_at": "2024-09-04T14:06:14.471Z",
        "updated_at": "2024-09-04T14:06:14.471Z"
      }
    }
  ],
  "payment_link": {
    "id": "2lbpkgbrBw4tYxnjonCDUVnUrfg",
    "plan_id": "2lbpkf3whsDiGXm1ECfRiXgnrYf",
    "invoice_id": "2lbpkhlbqWBbo4cd11brz8Ij75L",
    "source": "BoomFi",
    "metadata": "e30=",
    "customer_ident_collection": false,
    "shipping_address_collection": false,
    "tax_ident_collection": false,
    "enabled": true,
    "deleted_at": null,
    "properties": "e30=",
    "created_by": "",
    "updated_by": "",
    "created_at": "2024-09-04T14:06:14.505Z",
    "updated_at": "2024-09-04T14:06:14.505Z"
  },
  "org_id": "2Yy8BjDAxETxNZjFqRn4WWYEVHx",
  "org": {
    "id": "org_2Yy8BjDAxETxNZjFqRn4WWYEVHx",
    "name": "TestMerchant2"
  },
  "customer": {
    "id": "cus_2jdZlAbfpxZSY80bx81AqwuWuje",
    "org_id": "2Yy8BjDAxETxNZjFqRn4WWYEVHx",
    "name": "Test",
    "email": "[email protected]",
    "phone": "",
    "wallet_address": "0xF6F97412a831047D62A3B394107911619cAF7559",
    "deleted_at": null,
    "reference": "",
    "metadata": {},
    "created_at": "2023-12-02T03:05:24.144Z",
    "updated_at": "2023-12-02T03:05:24.4Z"
  },
  "event": "Invoice.Overdue"
}

Updated 3 months ago

What’s Next