Recurring Payments (Legacy) Webhooks

Set up webhooks for legacy recurring payments to receive start and end event notifications

Setting up a Pay Stream

Pay Streams are recurring payments, great for subscriptions or gated content.

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/stream/transaction

• HTTP Method: POST

• Required Query Parameters: ?apiKey={PUBLIC_API_KEY}

• Required Headers: Authorization: Bearer {SECRET_API_KEY}

Required request body:

{
     "streamId": "636a74162e72d4ad24ac9ce9",
     "targetUrl": "https://target-url.com/post-endpoint",
     "events": ["STARTED", "ENDED"]
  }

You can retrieve the streamId from the end of your Pay Stream URL. For example, in the URL https://app.hel.io/s/636a74162e72d4ad24ac9ce9, the streamId is 636a74162e72d4ad24ac9ce9

For streamId: 636a74162e72d4ad24ac9ce9, a similar curl command can be used to register recurring payment webhooks. The POST request is sent to targetUrl: https://target-url.com/post-endpoint.

curl -X POST \
  https://api.hel.io/v1/webhook/stream/transaction?apiKey=<apiKey> \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {apiSecret}' \
  -H 'cache-control: no-cache' \
  -d '
  {
     "streamId": "636a74162e72d4ad24ac9ce9",
     "targetUrl": "https://target-url.com/post-endpoint",
     "events": ["STARTED", "ENDED"]
  }
  '

In the following example we register a webhook to follow two events: stream STARTED, and stream ENDED

The response of this request will look as follows:

{
    "id": "636cf9c095aeedb263968ee9",
    "stream": "636a74162e72d4ad24ac9ce9",
    "company": "6343e77d91c393456aa56462",
    "targetUrl": "https://target-url.com/post-endpoint",
    "events": [
        "STARTED",
        "ENDED"
    ]
    "sharedToken": "security token"
}

When starting a stream on id 636cf9c095aeedb263968ee9 the targetUrl will receive the HTTP [POST] request with the following payload StreamEventPayload

export class StreamEventPayload {
  event: StreamTransactionEvent;
  transaction: PaystreamTransaction;
}

export class PaystreamTxWithMeta {
  meta: {
    id: string;
    transactionSignature: string;
    amount: string;
    recipientPK: string;
    senderPK: string;
    customerDetails: {
      email?: string;
      discordUsername?: string;
      twitterUsername?: string;
      fullName?: string;
      country?: string;
      deliveryAddress?: string;
      phoneNumber?: string;
      street?: string;
      streetNumber?: string;
      city?: string;
      areaCode?: string;
      additionalJSON?: string;
    };
    productDetails: {
      name?: string;
      value?: string;
    };
    splitRevenue: boolean;
    remainingAccounts: {
      amount: bigint;
      recipient: string;
    }[];
    totalAmount: number;
  };

  withdrawals: {
    paystreamTx: string;
    amount: string;
    fee?: string;
  }[];

  fee: string;

  paystream: string;

  id: string;

  paymentAccount: string;

  startedAt: {
    timestamp: string;
    transactionSignature: string;
  };

  createdAt: string;

  canceledAt: {
    timestamp: number;
    transactionSignature: string;
  } | null;

  endedAt: string;

  interval: number;

  paymentType: PaymentRequestType;

  active: boolean;

  isHelioX?: boolean;
}

export enum PaymentRequestType {
  PAYLINK = 'PAYLINK',
  PAYSTREAM = 'PAYSTREAM',
}

export enum StreamTransactionEvent {
  STARTED = 'STARTED',
  ENDED = 'ENDED',
}

View all webhooks created for a Pay Stream

You can list all the webhooks that have been created for a pay stream.

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/stream/transaction

• HTTP Method: GET

• Required Query Parameters: ?apiKey={PUBLIC_API_KEY}, streamId

• Required Headers: Authorization: Bearer {SECRET_API_KEY}

curl -X GET "https://api.hel.io/v1/webhook/stream/transaction?apiKey={PUBLIC_API_KEY}&streamId=6793b1ce1eaa655ae7aa1293" \
  -H "Authorization: Bearer {SECRET_API_KEY}" \
  -H "Accept: application/json"

This will return an array of all Webhooks that are registered for the Pay Stream. In case the API key isn't associated with stream, an unauthorised request error will be thrown.

[
    {
        "id": "636a3838591b00789e778b79",
        "stream": "636501dad706741f1ad63779",
        "company": "6343e77d91c393456aa56422",
        "targetUrl": "https://targetUrl.com",
        "events": [
            "STARTED",
            "ENDED"
        ]
    }
]