Webhook data is sent as JSON in the POST request body.
{
"event": "payment.successful",
"resource": {
"id": "MKFbh5LVpnFWipQNX9Qt3jLE",
"type": "payment",
"links": [
{
"rel": "self",
"href": "https://api.hips.com/v2/payments/MKFbh5LVpnFWipQNX9Qt3jLE",
"method": "GET"
}
],
"order_id": "oAZmBsFiq6r7ULK3jXRRh4Yo",
"status": "successful",
"currency": "USD",
"amount": 1000,
"order_status": "successful",
"merchant_order_id": null,
"meta_data_1": null,
"meta_data_2": null
},
"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJkYXRhIjp7ImV2ZW50IjoicGF5bWVudC5zdWNjZXNzZnVsIiwidHlwZSI6InBheW1lbnQiLCJyZXNvdXJjZSI6eyJpZCI6Ik1LRmJoNUxWcG5GV2lwUU5YOVF0M2pMRSIsImxpbmtzIjpbeyJyZWwiOiJzZWxmIiwiaHJlZiI6Imh0dHA6Ly9sb2NhbGhvc3Q6MzAwMC9hcGkvdjEvcGF5bWVudHMvTUtGYmg1TFZwbkZXaXBRTlg5UXQzakxFIiwibWV0aG9kIjoiR0VUIn1dLCJvcmRlcl9pZCI6Im9BWm1Cc0ZpcTZyN1VMSzNqWFJSaDRZbyIsInN0YXR1cyI6InN1Y2Nlc3NmdWwiLCJjdXJyZW5jeSI6IlVTRCIsImFtb3VudCI6MTAwMDAsIm9yZGVyX3N0YXR1cyI6InN1Y2Nlc3NmdWwiLCJtZXJjaGFudF9vcmRlcl9pZCI6bnVsbCwibWV0YV9kYXRhXzEiOm51bGwsIm1ldGFfZGF0YV8yIjpudWxsfX0sImlzcyI6ImhpcHMuY29tIn0.Lblr505ocNse5QyN9KLRU7tx-7iA5ShLKPjK9uBTO2bZGgXAnX6YqH1chxFLpXR3i5TCLm1a3D5bXHX6aRd5bj6zhgywEuaiJCA-b2aggbpxFAadaOgn_G5BqtMaOotf8vGep6d_zQJ7-Mp3Mp-uXDbYaj7rP4RE4QfMc32ng01ZGiGi1KJ4OlMQ3YHPcATlNAxyFv1hl_3QtoXzPYPfzRSqWtxcRnIy7mbrPUzK7WrJOMhPRy9zw7-vdRSqrpbl6bKHZS5SwnnMyXaU1ojbjAVf5Eq6hzUjkrdTUhTx17I3t4YS3gixh5YNj34bqkSujL3ZtQ0i9j0RBEkZnBiAaA"
}
Use webhooks to be notified about events that happen in a Hips account.
Interacting with a third-party API like Hips’s can introduce two problems:
- Services not directly responsible for making an API request may still need to know the response of that request
- Some events, like disputed charges and many recurring billing events, are not the result of a direct API request
Webhooks solve these problems by letting you register a URL that we will notify anytime an event happens in your account. When the event occurs—for example, when a successful charge is made on a customer’s subscription, Hips execute an webhook.
Available events. We have marked the events we recommend you to listen to with ✨.
| Event | Description |
|---|---|
| order.fulfilled | When order is marked as fulfilled. This will also capture any authorized but not captured payment on the order. |
| order.credited | Full or part of order refunded |
| order.recurring.canceled ✨ | When recurring contract is cancelled by the user or by too many failed retries. |
| order.recurring.successful | When a recurring payment is authorized |
| order.recurring.failed | When a recurring payment is declined |
| order.successful | When a order is fully paid and payments are captured |
| order.expired | When a order is abandoned (no payments) |
| order.modified | Every time an order is changed |
| order.recurring.retry | When a failed recurring payment is retrying payment |
| payment.created | When a payment is created |
| payment.successful | When a payment is captured / purchase. You will not get this for pre-authorizations until they are captured (regardless of payment method (refund, purchase etc). |
| payment.failed | When a payment is declined (regardless of payment method (refund, purchase etc). |
| payment.purchase.authorized ✨ | When a purchase payment is authorized |
| payment.purchase.successful ✨ | When a purchase payment is captured |
| payment.purchase.failed ✨ | When a purchase payment is failed |
| payment.credit.successful | When a credit is posted to your account |
| payment.credit.failed | When a credit failed to post on your account |
| payment.refund.successful ✨ | When a refund was approved |
| payment.refund.failed ✨ | When a refund failed |
| payment.chargeback.successful ✨ | When a chargeback was approved and debited. |
| payment.chargeback.representment.successful | When a chargeback dispute was won |
| payment.chargeback.representment.failed | When a chargeback dispute was lost |
| payment.voided ✨ | When a authorized payment was voided (refunded) |
| payout.created | When a payout was created |
| payout.successful | When a payout was sent to bank |
| sales.channel.approved | When a new sales channel was approved |
| sales.channel.rejected | When a sales channel was rejected or terminated |
| sales.channel.verification.expired | When the verification time on a sales channel expired (new verification required) |
| sales.channel.removed | When a sales channel is removed |
| sales.channel.api.key.rolled | When the API keys on a sales channel is rolled/renewed |
| sales.channel.created | When a new sales channel is created |
| merchant.bank_account.created | When a new bank account is added to the merchant |
| merchant.signup | When a new merchant signed up (for partners only) |
| merchant.application.created | When a new merchant application is submitted (for partners only) |
| merchant.application.in_review | When a merchant application is in review state (for partners only) |
| merchant.application.approved | When a merchant application is approved (for partners only) |
| merchant.application.declined | When a merchant application is declined (for partners only) |
| merchant.device.new | When a new device logged in to the account |
| sales.channel.verified | When a sales channel is verified |
| sales.channel.verification.needs_merchant_attention | When a sales channel have something that needs the merchants attention. Most often a chat message from the compliance team. For websites this can be a request to remove an prohibited product or update terms and conditions. |
| payment.authorization.expired ✨ | This is sent if a pre-authorization is not captured within 7 days. A new authorization will be required. |
| iot.sim_first_online | For Hips IoT SIM Cards in terminals. Sent first time we see the SIM card connected to a mobile network. |
| iot.inactive_5_days | For Hips IoT SIM Cards in terminals. If the SIM has not been connected to a mobile network for 5 days. |
| iot.inactive_30_days | For Hips IoT SIM Cards in terminals. If the SIM has not been connected to a mobile network for 30 days. |
| iot.country_change | For Hips IoT SIM Cards in terminals. If the SIM changes country. |
| iot.80_percent_of_data_consumed | For Hips IoT SIM Cards in terminals. If 80% if the allowed data plan for the specific SIM is consumed. (You should consider to add more data) |
| iot.all_monthly_data_consumed | For Hips IoT SIM Cards in terminals. If 100% if the allowed data plan for the specific SIM is consumed. SIM card will go in to suspend mode.(You should consider to add more data) |
| iot.active | For Hips IoT SIM Cards in terminals. Then a SIM is activated or resumed from suspend or pause state |
| iot.paused | For Hips IoT SIM Cards in terminals. Same as suspend |
| iot.suspended | For Hips IoT SIM Cards in terminals. Card data is temporary blocked. |
| iot.deactivated | For Hips IoT SIM Cards in terminals. Card is deactivated and unregistered from the mobile carrier. |
| iot.closed | For Hips IoT SIM Cards in terminals. Card is closed and terminated. It cannot be used anymore. |
Webhook retry policy
Webhooks will retry with the same Idempotency-Key in the header for a maximum of 5 times with a delay of 60 minutes between each retry. If there is no 2xx http response from the server within the retry window, the web hook will be discarded.
If you know that you had a server downtime of more than 5 hours, you should re-sync transactions from the payment or order api for your down window.