Subscription Webhooks

Set up webhooks for subscriptions to track when they start, renew, and end

You can set up webhooks for your subscription payments to receive events when a user starts a new subscription, renews an existing one or when a subscription is ended.

Setting up a webhook

NOTE: When using the production environment (app.hel.io), set your API endpoint to api.hel.io/v1 and generate API keys there. For the development environment, use api.dev.hel.io/v1 and generate API keys from app.dev.hel.io.

• API Endpoint: https://api.hel.io/v1/webhook/paylink/subscription

• HTTP Method: POST

• Required Query Parameters: ?apiKey={Your public key here}

• Required Headers: Authorization: Bearer {Your API Token here}

Request Body:

{
    "paylinkId": "{id}",
    "targetUrl": "{targetUrl}",
    "events": ["STARTED","RENEWED", "ENDED"]
}

• “STARTED” – Triggered when a subscription begins after payment.

• “RENEWED” – Triggered when a subscription is renewed.

• “ENDED” – Triggered when a subscription expires or is canceled due to non-payment.

This is an example of a curl command to register a subscription webhook for paylinkID: 679bb9db7f3c16eb86bb1c67 triggered by the STARTED event upon transaction confirmation.

This sends a POST request to targetUrl: https://target-url.com/post-endpoint.

curl -X POST \
  https://api.hel.io/v1/webhook/paylink/subscription?apiKey=YOUR_API_KEY \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_SECRET' \
  -H 'cache-control: no-cache' \
  -d '
  {
     "paylinkId": "679bb9db7f3c16eb86bb1c67",
     "targetUrl": "targetUrl: https://target-url.com/post-endpoint",
     "events": ["STARTED"]
  }'

The response of this request will look like:

{
    "id": "679cb0a5eafd565eeab89605",
    "paylink": "679bb9db7f3c16eb86bb1c67",
    "company": "6683f4efc330474ede1f25aa",
    "targetUrl": "targetUrl: https://target-url.com/post-endpoint",
    "events": [
        "STARTED"
    ],
    "sharedToken": "ZtiSEjZsTNoczv8kvDgtSx5+YO017NOlM/mrqEMj2nnHXi+UfmCQvuqvZlI0eH3JJWrW1D3UDWM+GgK9sVfR0NNPIMwWNV+jcFehjDIMlVq05Ahf2/5tUT/W7qqiHWZy"
}

A unique token generated at webhook creation is included with each webhook as authorization: Bearer SHARED_TOKEN, verifying the webhook source as Helio.

Note: Retain this token to authenticate and delete web hooks if needed.

Upon successful payment on Pay Link 679bc67238ad367780fc7cf1, the targetUrl will receive an HTTP [POST] request with the following payload:

{
  "event": "STARTED",
  "email": "[e-mail]",
  "subscriptionState": "NEW",
  "subscriptionId": "67a2398e353a885e45cc7651",
  "transactionObject": {
    "id": "67a239887e23092b632feded",
    "paylinkId": "67a23795353a885e45cc6d6a",
    "fee": "2000",
    "quantity": 1,
    "createdAt": "2025-02-04T16:00:08.368Z",
    "paymentType": "PAYLINK",
    "meta": {
      "id": "67a239887e23092b632fedeb",
      "amount": "98000",
      "senderPK": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW",
      "recipientPK": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW",
      "transactionType": "PAYLINK",
      "customerDetails": {
        "email": "[e-mail]",
        "discordUser": null
      },
      "productDetails": null,
      "additionalProductDetails": [],
      "transactionSignature": "5AmMWzAjCLnYo36xyDHRDWoeAtF3113b6FA1RJiNRidmAuUHRYyQ2dkJuTTPaNUpurSzMEyBimu3GbRLVyHrwSA1",
      "transactionStatus": "SUCCESS",
      "splitRevenue": false,
      "remainingAccounts": [],
      "totalAmount": "98000",
      "affiliateAmount": "0",
      "tokenQuote": {
        "from": "USDC",
        "fromAmountDecimal": "0.1",
        "to": "USDC",
        "toAmountMinimal": "100000"
      },
      "shopifyPaymentDetails": null,
      "submitGeolocation": "GB",
      "currency": {
        "id": "63430c8348c610068bcdc482",
        "blockchain": null
      }
    }
  }

Note: When you create or list Pay Link webhooks, a sharedToken is generated. This token is sent to your endpoint as authorization: Bearer SHARED_TOKEN to validate that the webhook originates from Helio.