Webhooks

📘

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:

  1. Services not directly responsible for making an API request may still need to know the response of that request
  2. 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 ✨.

EventDescription
order.fulfilledWhen order is marked as fulfilled. This will also capture any authorized but not captured payment on the order.
order.creditedFull or part of order refunded
order.recurring.canceled ✨When recurring contract is cancelled by the user or by too many failed retries.
order.recurring.successfulWhen a recurring payment is authorized
order.recurring.failedWhen a recurring payment is declined
order.successfulWhen a order is fully paid and payments are captured
order.expiredWhen a order is abandoned (no payments)
order.modifiedEvery time an order is changed
order.recurring.retryWhen a failed recurring payment is retrying payment
payment.createdWhen a payment is created
payment.successfulWhen 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.failedWhen 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.successfulWhen a credit is posted to your account
payment.credit.failedWhen 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.successfulWhen a chargeback dispute was won
payment.chargeback.representment.failedWhen a chargeback dispute was lost
payment.voided ✨When a authorized payment was voided (refunded)
payout.createdWhen a payout was created
payout.successfulWhen a payout was sent to bank
sales.channel.approvedWhen a new sales channel was approved
sales.channel.rejectedWhen a sales channel was rejected or terminated
sales.channel.verification.expiredWhen the verification time on a sales channel expired (new verification required)
sales.channel.removedWhen a sales channel is removed
sales.channel.api.key.rolledWhen the API keys on a sales channel is rolled/renewed
sales.channel.createdWhen a new sales channel is created
merchant.bank_account.createdWhen a new bank account is added to the merchant
merchant.signupWhen a new merchant signed up (for partners only)
merchant.application.createdWhen a new merchant application is submitted (for partners only)
merchant.application.in_reviewWhen a merchant application is in review state (for partners only)
merchant.application.approvedWhen a merchant application is approved (for partners only)
merchant.application.declinedWhen a merchant application is declined (for partners only)
merchant.device.newWhen a new device logged in to the account
sales.channel.verifiedWhen a sales channel is verified
sales.channel.verification.needs_merchant_attentionWhen 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_onlineFor Hips IoT SIM Cards in terminals. Sent first time we see the SIM card connected to a mobile network.
iot.inactive_5_daysFor Hips IoT SIM Cards in terminals. If the SIM has not been connected to a mobile network for 5 days.
iot.inactive_30_daysFor Hips IoT SIM Cards in terminals. If the SIM has not been connected to a mobile network for 30 days.
iot.country_changeFor Hips IoT SIM Cards in terminals. If the SIM changes country.
iot.80_percent_of_data_consumedFor 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_consumedFor 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.activeFor Hips IoT SIM Cards in terminals. Then a SIM is activated or resumed from suspend or pause state
iot.pausedFor Hips IoT SIM Cards in terminals. Same as suspend
iot.suspendedFor Hips IoT SIM Cards in terminals. Card data is temporary blocked.
iot.deactivatedFor Hips IoT SIM Cards in terminals. Card is deactivated and unregistered from the mobile carrier.
iot.closedFor 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.