Getting started with our webhooks
ℹ️ To see Webhooks in action, with code examples, check out our recipes.
What are Webhooks?
Helio Webhooks allow developers to listen to Helio payment events and verify transactions on your application's backend.
Webhooks are linked to your Helio account and use a sharedSecret with a Bearer auth header to authenticate endpoints. You can generate your API key in the Helio dashboard. Webhooks are supported for Pay Links on Solana, Ethereum, Base, Polygon, and BTC, as well as Pay Streams (recurring payments) on Solana.
Webhook Payload Example
Our webhooks include detailed information about the transaction and Pay Link.
{ // the PaylinkEventPayload object
"transaction": "...", // JSON string of the transactionObject below
"event": "CREATED", // PaylinkEvents enum - matches the webhook event type when creating the webhook
"transactionObject": {
"id": "65e1df4d0ce08148bc333b62", // Helio transaction ID
"paylinkId": "65dc9f9f1154beaac39976c8", // Paylink ID
"quantity": 1,
"createdAt": "2024-03-01T13:59:41.303Z",
"paymentType": "PAYLINK", // or 'PAYSTREAM'
"meta": { // the TransactionMeta object
"id": "65e1df4d0ce08148bc333b60",
"amount": "9900000", // amount in minimal units (lamport/Sats/Wei)
"senderPK": "Er3RwfYqCETBTf5RktezXaNDT3zYgwBMftxBYbX8Zk1G", // customer's wallet
"recipientPK": "Er3RwfYqCETBTf5RktezXaNDT3zYgwBMftxBYbX8Zk1G", // merchant's recipient wallet
"customerDetails": {
"country": "United States",
"deliveryAddress": "test-address",
"email": "[email protected]",
"fullName": "test-full-name",
"phoneNumber": "+0123123123123",
"discordUsername": "a11111118100",
"discordUser": {
"id": "1234567890",
"username": "test-discord-username"
},
"twitterUsername": "test-x-username",
"state": "test-state",
"street": "test-street",
"streetNumber": "123",
"areaCode": "90210",
"city": "test-city"
"additionalJSON": "\"{\\\"test\\\": 123}\"" // any additionalJSON will be JSON stringified
},
"productDetails": null,
"transactionSignature": "5AYzruixQiGX8rm279cPLo7bdqaUPYMD8Z3QnBNVz2omZHaUsUKFZRmaV8W7sAHPEyExeHkjquy8mg6LHcNktg5c",
"transactionStatus": "SUCCESS",
"splitRevenue": false,
"remainingAccounts": [],
"totalAmount": "9900000",
"affiliateAmount": "0", // Amount sent to affiliate who referred the transaction. This will normally be "0" unless referred by affiliate
"affiliateCode": "somecode", // Affiliate code used - this will normally be undefined
"affiliatePublicKey": "Er3RwfYqCETBTf5RktezXaNDT3zYgwBMftxBYbX8Zk1G"; // Public key (wallet address) for affiliate who referred this transaction. This will normally be undefined
"tokenQuote": {
"from": "SOL",
"fromAmountDecimal": "0.01",
"to": "SOL",
"toAmountMinimal": "10000000"
},
"submitGeolocation": "FR", // ISO 3166-1 alpha-2 country code based on IP address which submitted the transaction to our server
"currency": {
"id": "63430c8348c610068bcdc474",
"blockchain": null
}
}
}
}Authenticating Webhooks with Bearer Token
A unique token generated at webhook creation is included with each webhook request as an Authorization: Bearer SHARED_TOKEN header, verifying that the webhook is sent from Helio.
{
"id": "636cf9c095aeedb263968ee9",
"paylink": "636a74162e72d4ad24ac9ce9",
"company": "6343e77d91c393456aa56462",
"targetUrl": "https://target-url.com/post-endpoint",
"events": [
"CREATED"
]
"sharedToken": "PGpDZdZdxjdN+VgoxR/RHItMj0gq2BK5tEZtIisfyKe4M8l0B51qED/YqSSPwfAVtonvdXKhn+9j63b4krxGWNkO3hyPQiiu1SD2uttjEAdMeUO+3QoTNAwxuH1FzwyP"
}Note: Retain this token, as it is required to authenticate and delete webhooks if needed.
Retrieving Geolocation from the Webhook Payload
The submitGeolocation field in the webhook payload provides the ISO 3166-1 alpha-2 country code representing the location of the IP address that initiated the transaction. This field is useful for understanding the geographic source of transactions. See the code example below, taken from the webhook payload.
"submitGeolocation": "FR"
// ISO 3166-1 alpha-2 country code based on IP address which submitted the
transaction to our serverView our API reference to learn how to setup webhooks.