Helio
Search…
⌃K
Links
🪝

Webhooks

Setup powerful event-driven payment workflows in minutes

What are Webhooks?

Helio Webhooks let you listen to Helio payments events (both on & off-chain data). Examples are listening to incoming transactions, payments, invoices paid, subscriptions created, paused or cancelled events. This allows developers to create powerful features and real-time workflows around events on the Helio stack including paywalls, subscription payments and integrations.
We currently support webhooks on payment streams (subscriptions) and paylinks (one time payments).
Security: Webhooks are linked to your Helio account. In order to access to them you need to log in to our Dashboard with your wallet and generate your API key
Each Webhook generates a `sharedSecret` used with the target API to authenticate the endpoints with a Bearer auth header.

API endpoints

For paylinks and paystreams we provide 4 API endpoints each for creating, listing, getting Webhooks by ID, and deleting a Webhook. API specs are published below:
get
/v1/webhook/stream/transaction
post
/v1/webhook/stream/transaction
get
/v1/webhook/stream/transaction/{webhookId}
delete
/v1/webhook/stream/transaction/{webhookId}

Creating a Webhook

The following is a curl command that will register the Webhook for paylinkID: 636a74162e72d4ad24ac9ce9 on new transaction event. This will send a POST request to targetUrl: https://target-url.com/post-endpoint.
curl -X POST \
https://api.hel.io/v1/webhook/paylink/transaction?apiKey=<apiKey> \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {apiSecret}' \
-H 'cache-control: no-cache' \
-d '
{
"paylinkId": "636a74162e72d4ad24ac9ce9",
"targetUrl": "https://target-url.com/post-endpoint",
"events": ["CREATED"]
}
'
The API key needs to be associated with the same account of the underlying Pay Link in order to register the Webhook.
The response of this request will look as follows:
{
"id": "636cf9c095aeedb263968ee9",
"paylink": "636a74162e72d4ad24ac9ce9",
"company": "6343e77d91c393456aa56462",
"targetUrl": "https://target-url.com/post-endpoint",
"events": [
"CREATED"
]
}
Upon payment on the Pay Link 636cf9c095aeedb263968ee9 the targetUrl will receive HTTP [POST] request with the following payload:
export class Transaction {
id: string;
quantity: number;
fee?: string;
createdAt: string;
paymentType: PaymentRequestType;
meta: Meta;
}
export class Meta {
id: string;
transactionSignature: string;
amount: bigint;
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: string;
recipient: string;
}[];
totalAmount: string;
currency: {
id: string;
symbol: string;
name: string;
mintAddress: string;
coinMarketCapId: number;
decimals: number;
symbolPrefix?: string;
order: number;
};
}
export enum PaymentRequestType {
PAYLINK = 'PAYLINK',
PAYSTREAM = 'PAYSTREAM',
}

Listing Webhooks

You can list all the hooks that are registered for a Pay Link with the following curl reuqest:
curl \
https://api.hel.io/v1/webhook/paylink/transaction?apiKey=Uus~N8ePqcG8jaYxFfGajGu3US.Y8XlicIZwEoUqT~YGy7A7qjE-o-QXDN1N7MwF&paylinkId=636501dad706741f1ad63770
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {apiSecret}' \
-H 'cache-control: no-cache'
This will return an array of all Webhooks that are registered for the Pay Link. In case the API key isn't associated with Pay Link, an unauthorised request will be thrown.
[
{
"id": "636a3838591b00789e778b79",
"paylink": "636501dad706741f1ad63779",
"company": "6343e77d91c393456aa56422",
"targetUrl": "https://targetUrl.com",
"events": [
"CREATED"
]
}
]

Deleting Webhook

You can delete any Webhook ID by calling the delete endpoint:
curl -X DELETE \
https://api.hel.io/v1/webhook/paylink/transaction/636a75ee5a9078bb9803a681?apiKey=Uus~N8ePqcG8jaYxFfGajGu3US.Y8XlicIZwEoUqT~YGy7A7qjE-o-QXDN1N7MwF
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {apiSecret}' \
-H 'cache-control: no-cache'
To be clear, in this example, 636a75ee5a9078bb9803a681 is the ID of the Webhook.

Paystream examples

Creating a Webhook

The following is a curl command that will register the Webhook for streamId: 636a74162e72d4ad24ac9ce9 on new transaction event. This will send a POST request 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"]
}
'
The API key needs to be associated with the same account of the underlying Stream in order to register the Webhook.
In the following example we register a Webhook to follow two events: stream start, and stream end
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',
}
Important every POST request to targetUrl includes Authorization header with Bearer token, which is the sharedSecret. The API consumer can choose to authenticate their endpoint with the following token.

Listing Webhooks

You can list all the hooks that are registered for a stream with the following curl reuqest:
curl \
https://api.hel.io/v1/webhook/stream/transaction?apiKey=Uus~N8ePqcG8jaYxFfGajGu3US.Y8XlicIZwEoUqT~YGy7A7qjE-o-QXDN1N7MwF&streamId=636501dad706741f1ad63770
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {apiSecret}' \
-H 'cache-control: no-cache'
This will return an array of all Webhooks that are registered for the 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"
]
}
]

Deleting Webhooks

You can delete any Webhook ID by calling the delete endpoint:
curl -X DELETE \
https://api.hel.io/v1/webhook/stream/transaction/636a75ee5a9078bb9803a681?apiKey=Uus~N8ePqcG8jaYxFfGajGu3US.Y8XlicIZwEoUqT~YGy7A7qjE-o-QXDN1N7MwF
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {apiSecret}' \
-H 'cache-control: no-cache'
To be clear, in this example, 636a75ee5a9078bb9803a681 is the ID of the Webhook.