Set up webhooks for Pay Links to receive payment success notifications
Creating a Pay Link 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.
This is an example of a curl command to register a webhook for paylinkID: 636a74162e72d4ad24ac9ce9 triggered by the CREATED event upon transaction confirmation.
This sends a POST request to targetUrl: https://target-url.com/post-endpoint.
Note: For Pay Link web hooks CREATED is the only event. It's fired when the transaction is confirmed on the blockchain and within Helio's system (near-instant for Solana).
The response of this request will look as follows:
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 636cf9c095aeedb263968ee9, the targetUrl will receive an HTTP [POST] request with the following payload:
class PaylinkEventPayload {
event: PaylinkEvents; // e.g. 'CREATED'
transaction: string; // JSON string value of the transactionObject
transactionObject: Transaction;
}
class Transaction {
id: string;
paylinkId: string;
quantity: number;
fee?: string;
createdAt: string;
paymentType: PaymentRequestType;
claimDetails: {
tradingView?: {
username: string;
};
discord?: {
username: string;
};
};
meta: TransactionMeta;
}
enum TransactionStatus {
INITIATED = 'INITIATED',
PENDING = 'PENDING',
SUCCESS = 'SUCCESS',
FAILED = 'FAILED',
CANCELED = 'CANCELED',
SETTLED = 'SETTLED',
}
class TransactionMeta {
id: string;
transactionSignature: string; // transaction hash on the blockchain
amount: string;
recipientPK: string; // merchant's public key (wallet address)
senderPK: string; // customer's public key (wallet address)
customerDetails: {
email?: string;
discordUsername?: string;
discordUser?: {
id: string
username: string
}
twitterUsername?: string;
fullName?: string;
country?: string;
deliveryAddress?: string;
phoneNumber?: string;
street?: string;
streetNumber?: string;
city?: string;
state?: string
areaCode?: string;
additionalJSON?: string;
};
productDetails: { // From 'advanced options' (step 3 of paylink creation) -> additional information
name?: string;
value?: string;
};
splitRevenue: boolean;
remainingAccounts: {
amount: string;
recipient: string;
}[];
totalAmount: string;
affiliateAmount: string;
affiliateCode?: string;
affiliatePublicKey?: string;
currency: {
id: string;
blockchain?: { engine: BlockchainEngine } | null;
};
transactionType?: TransactionType;
tokenQuote?: TokenQuoteMeta;
transactionStatus: TransactionStatus // e.g. 'SUCCESS'
}
// used for converting between pricing currency (from) and what they paid with (to)
// note: from could be a crypto currency (e.g. (0.1 ETH), or fiat currency (e.g. $5)
// to is always going to be a crypto currency.
// This is useful when using swaps, to see what they paid
class TokenQuoteMeta {
from: string;
fromAmountDecimal: string;
to: string;
toAmountMinimal: string;
}
class BlockchainEngine {
id: string;
type: BlockchainEngineType;
}
enum PaymentRequestType {
PAYLINK = "PAYLINK",
PAYSTREAM = "PAYSTREAM",
}
enum PaylinkEvents {
CREATED = "CREATED",
}
enum TransactionType {
REFUND = "REFUND",
PAYLINK = "PAYLINK",
}
enum BlockchainEngineType {
EVM = "EVM",
SOL = "SOL",
BTC = "BTC",
}
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.
View all webhooks created for a Pay Link
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.
You can list all the hooks that are registered for a Pay Link with the following curl request:
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.
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.
You can delete any Webhook ID by calling the delete endpoint:
To be clear, in this example, 636a75ee5a9078bb9803a681is the ID of the Webhook. You can get this when you create a webhook, or by listing all webhooks for a Pay Link
