Helio Webhooks allow developers to listen to Helio payment events and verify transactions on your application's backend.
Security: Webhooks are linked to your Helio account. Log in to the Helio dashboard to generate your API key. Each Webhook generates a `sharedSecret` used with the target API to authenticate the endpoints with a Bearer auth header.
Support: Webhooks are available for Helio 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": "test@example.com",
"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
}
}
}
}
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 server
