Webhooks

What are webhooks

Webhooks are a lightweight one-way communication medium for Suberra to inform merchants of actions taken by their subscribers - such as when there is a new subscriber or when there is a lapse in payments. They allow merchants to handle payment events without having to constantly poll an endpoint.

Using webhooks with Suberra

Merchants will need to setup an endpoint in the Merchant Dashboard, which will receive the webhook payload. The endpoint will need to be able to handle the payload and respond with a 200 status code. If the endpoint does not respond with a 200 status code, Suberra will retry the request.

Events

Overview

Event	Description
subscription.created	Fired when a subscription is created
subscription.renewed	Sent when the subscription is successfully renewed, after the payment is confirmed.
subscription.cancelled	Fired when a merchant cancels a user's subscription before it's natural end
subscription.past_due	Fired when a user's subscription's due_date is past_due and user hasn't paid successfully
invoice.created	Sent when a successful payment for a product is made.
charge.failed	Sent when an charge attempt failed for dued invoice or subscription.

Example Payloads

Recurring payment

New subscriber:

{
  "id": "evt_OGpi7xz7f134fvalhhoha12qmnpb87ae",
  "external_id": "evt_OGpi7xz7f134fvalhhoha12qmnpb87ae",
  "type": "subscription.created",
  "version": "0.1.0",
  "data": {
    "id": "sub_OGsiik5mfuzte6d04gb46dtfm2y7",
    "status": "ACTIVE",
    "status_reason": null,
    "period_start": "2023-04-12T05:53:13.000Z",
    "period_end": "2023-04-13T05:53:13.000Z",
    "currency": "USDC",
    "unit_amount": "0.1",
    "updated_at": "2023-04-12T05:53:28.998Z",
    "status_updated_at": "2023-04-12T05:53:28.998Z",
    "interval": "DAY",
    "interval_count": 1,
    "plan_cycle_count": 1,
    "first_charge_amount": null,
    "required_fields_data": {
      "email": "john@suberra.com"
    },
    "trial_used": false,
    "invoice": {
      "due_at": "2023-04-12T05:53:09.750Z",
      "status": "PAID",
      "paid_at": "2023-04-12T05:53:13.000Z",
      "charge_attempts": null,
      "tx_hash": "0x20f9f6a280f5bc99a358bf659f7951a7c5fac952ec8536cca2a43efc3ad703b6",
      "chain_id": "42161",
      "unit_amount": "0.1",
      "currency": "USDC",
      "meta_data": null,
      "id": "in_OGfjayky6gcv53jsn01xb26kaq2qg",
      "user_address": "0x7f9c5d92a0722293157427019658fc648436e6f0",
      "status_reason": null,
      "is_trial_payment": false,
      "required_fields_data": {
        "email": "john@suberra.com"
      },
      "network": "arbitrum_one"
    },
    "paymentLink": {
      "plan": {
        "interval": "DAY",
        "interval_count": 1
      },
      "status": "ACTIVE",
      "currency": "USDC",
      "link_ttl": null,
      "meta_data": {},
      "expired_at": null,
      "description": "Latest alpha straight to your inbox!",
      "lookup_code": "OGjiv3eh1678833388281",
      "unit_amount": "0.1",
      "multiple_use": true,
      "payment_type": "SUBSCRIPTION",
      "link_active_at": null,
      "first_charge_amount": null,
      "purchasable_quantity": null,
      "end_after_plan_cycle_count": null,
      "is_unique_address_purchase": false,
      "trial_plan": null,
      "products": [
        {
          "id": "prod_OGp2cyzjrvdvj8ibwuqnfjz4",
          "name": "Alpha Daily Insights",
          "description": "Latest alpha straight to your inbox!",
          "currency": "USDC",
          "price": "0.1",
          "required_fields": ["email"]
        }
      ]
    },
    "merchant": {
      "id": "485cf97d-d6b5-498f-917e-9893dc806dd7",
      "name": "Suberra Merch Shop",
      "email": "shop@suberra.com",
      "op_code": "OG",
      "webhook_url": "https://api.suberra.com/webhook/114f1a9e-d5a8-43b7-a50f-d5bb1c9403bf"
    },
    "is_trial": false
  }
}

On subscription renewal:

{
  "id": "evt_OGqiwxcc77mxoug3llrmo6lo65h98vrg",
  "external_id": "evt_OGqiwxcc77mxoug3llrmo6lo65h98vrg",
  "type": "subscription.renewed",
  "version": "0.1.0",
  "data": {
    "id": "sub_OGwomzzbi1hgdkst215xrbawgho4",
    "status": "ACTIVE",
    "status_reason": null,
    "period_start": "2023-03-29T04:28:50.000Z",
    "period_end": "2023-03-30T04:28:50.000Z",
    "currency": "USDC",
    "unit_amount": "0.1",
    "updated_at": "2023-03-31T05:00:34.494Z",
    "status_updated_at": "2023-03-31T05:00:34.494Z",
    "interval": "DAY",
    "interval_count": 1,
    "plan_cycle_count": 7,
    "first_charge_amount": null,
    "required_fields_data": { "email": "john@suberra.com" },
    "trial_used": false,
    "merchant": {
      "id": "485cf97d-d6b5-498f-917e-9893dc806dd7",
      "name": "Suberra Merch Shop",
      "email": "shop@suberra.com",
      "op_code": "OG",
      "webhook_url": "https://api.suberra.com/webhook/114f1a9e-d5a8-43b7-a50f-d5bb1c9403bf"
    },
    "paymentLink": {
      "plan": {
        "interval": "DAY",
        "interval_count": 1
      },
      "status": "ACTIVE",
      "currency": "USDC",
      "link_ttl": null,
      "meta_data": {},
      "expired_at": null,
      "description": "Latest alpha straight to your inbox!",
      "lookup_code": "OGjiv3eh1678833388281",
      "unit_amount": "0.1",
      "multiple_use": true,
      "payment_type": "SUBSCRIPTION",
      "link_active_at": null,
      "first_charge_amount": null,
      "purchasable_quantity": null,
      "end_after_plan_cycle_count": null,
      "is_unique_address_purchase": false,
      "products": [
        {
          "id": "prod_OGp2cyzjrvdvj8ibwuqnfjz4",
          "name": "Alpha Daily Insights",
          "description": "Latest alpha straight to your inbox!",
          "currency": "USDC",
          "price": "0.1",
          "required_fields": ["email"]
        }
      ]
    },
    "invoice": {
      "due_at": "2023-03-31T05:00:19.778Z",
      "status": "PAID",
      "paid_at": "2023-03-31T05:00:11.000Z",
      "charge_attempts": 3,
      "tx_hash": "0x997279158e7fa881c3402f8a9b3e4079a226dc10cbc0697b2e379aa6a3c474ac",
      "chain_id": "42161",
      "unit_amount": "0.1",
      "currency": "USDC",
      "meta_data": null,
      "id": "in_OGtvphlaz6m8f6j40c4sn5vf9dp3f",
      "user_address": "0xbf48e3c04478c9fbe516a431c8866dc6908277e2",
      "status_reason": null,
      "is_trial_payment": false,
      "network": "arbitrum_one"
    }
  }
}

One-time payment

When a product is purchased:

{
  "id": "evt_OGj03m5z9ykpxdwxk0zf9zb3av4t1eqv",
  "external_id": "evt_OGj03m5z9ykpxdwxk0zf9zb3av4t1eqv",
  "type": "invoice.created",
  "version": "0.1.0",
  "data": {
    "due_at": "2023-04-11T06:59:29.706Z",
    "status": "PAID",
    "paid_at": "2023-04-11T06:59:35.000Z",
    "charge_attempts": null,
    "tx_hash": "0x9e0d6fdd4c934779a356f7c3576ebf52ed1095abeb0a9bdfaa50084f43ead89c",
    "chain_id": "137",
    "unit_amount": "0.01",
    "currency": "USDC",
    "meta_data": null,
    "id": "in_OGa2tdkqlxuti1vbg18yxulbrudj5",
    "user_address": "0x7f9c5e92a0522292157427019658fc848436e4f0",
    "status_reason": null,
    "is_trial_payment": false,
    "required_fields_data": {
      "name": "John Smith",
      "email": "john@suberra.com"
    },
    "network": "polygon",
    "merchant": {
      "id": "485cf97d-d6b5-498f-917e-9893dc806dd7",
      "name": "Suberra Merch Shop",
      "email": "shop@suberra.com",
      "op_code": "OG",
      "webhook_url": "https://api.suberra.com/webhook/114f1a9e-d5a8-43b7-a50f-d5bb1c9403bf"
    },
    "paymentLink": {
      "plan": null,
      "status": "ACTIVE",
      "currency": "USDC",
      "link_ttl": null,
      "meta_data": {},
      "expired_at": null,
      "description": "Lightweight, responsive, ultra-comfortable, combining performance and style for limitless running.",
      "lookup_code": "OGe53m8doos3dw8s8ihlap0n",
      "unit_amount": "59.99",
      "multiple_use": true,
      "payment_type": "PRODUCT",
      "link_active_at": null,
      "first_charge_amount": null,
      "purchasable_quantity": null,
      "end_after_plan_cycle_count": null,
      "is_unique_address_purchase": false,
      "trial_plan": null,
      "products": [
        {
          "id": "prod_OGr23hxe8ig6mwtzh3afy8k9",
          "name": "A-One Running Shoe",
          "description": "Lightweight, responsive, ultra-comfortable, combining performance and style for limitless running.",
          "currency": "USDC",
          "price": "59.99",
          "required_fields": ["email", "name"]
        }
      ]
    }
  }
}

What are webhooks​

Using webhooks with Suberra​

Events​

Overview​

Example Payloads​

Recurring payment​

One-time payment​