Introduction
Webhooks allow you to set up integrations which subscribe to certain events from your Payhip store.
There are 4 webhook events available for you to listen from:
- paid — Occurs whenever a customer is charged
- refunded — Occurs whenever a payment is refunded
- subscription.created — Occurs whenever a customer has started a subscription
- subscription.deleted — Occurs whenever a customers subscription is canceled
We can send you a HTTP POST payload to the webhook’s configured URL. Webhooks can be used to tweet a new sale, add a line to a Google spreadsheet, add a buyer to an email subscriber list and much more.
Please make sure the webhook’s configured URL returns a 200 HTTP status code. If your endpoint does not return a 200 HTTP status code, the POST is retried once an hour for up to 3 hours.
Enabling webhooks
Please visit your Settings page and then click on the Developer tab
Next paste in your webhook endpoint. You can have multiple webhook endpoints by comma separating them in that field.
Finally select the webhook events you would like to listen for.
"paid" event
This is an example of the JSON response you will find in the body of the HTTP POST payload:
{
"id": "ZGjVj5x4GN",
"email": "johndoe@example.com",
"currency": "USD",
"price": 900,
"vat_applied": false,
"ip_address": "72.334.28.154",
"items": [
{
"product_id": "2804256",
"product_name": "The Adventures of Sherlock Holmes",
"product_key": "RGsF",
"product_permalink": "https://payhip.com/b/RGsF",
"quantity": "1",
"on_sale": false,
"used_coupon": false,
"used_social_discount": false,
"used_cross_sell_discount": false,
"used_upgrade_discount": false,
"promoted_by_affiliate": false,
"has_variant": false
}
],
"payment_type": "card",
"stripe_fee": 48,
"payhip_fee": 33,
"unconsented_from_emails": false,
"is_gift": false,
"date": 1703693218,
"type": "paid",
"signature": "dbcdccb0dfc5a57rh704bc75d7bbb18hdd3ee85f4081d5c4adbff934622919d8"
}
The " id" parameter is the ID of the transaction
The " type" parameter lets you know this is a "paid" event
"refunded" event
This is an example of the JSON response you will find in the body of the HTTP POST payload:
{
"id": "ZGjVj5x4GN",
"email": "johndoe@example.com",
"currency": "USD",
"price": 900,
"vat_applied": false,
"ip_address": "72.334.28.154",
"items": [
{
"product_id": "2804256",
"product_name": "The Adventures of Sherlock Holmes",
"product_key": "RGsF",
"product_permalink": "https://payhip.com/b/RGsF",
"quantity": "1",
"on_sale": false,
"used_coupon": false,
"used_social_discount": false,
"used_cross_sell_discount": false,
"used_upgrade_discount": false,
"promoted_by_affiliate": false,
"has_variant": false
}
],
"payment_type": "card",
"stripe_fee": 48,
"payhip_fee": 33,
"unconsented_from_emails": false,
"is_gift": false,
"amount_refunded": 900,
"date_refunded": 1703693410,
"date_created": 1703693218,
"type": "refunded",
"signature": "dbcdccb0dfc5a57rh704bc75d7bbb18hdd3ee85f4081d5c4adbff934622919d8"
}
If the " amount_refunded" parameter matches the "price" parameter then this was a full refund, otherwise it's a partial refund
The " date_created" parameter is the date this transaction was created
The " date_refunded" parameter is the date this transaction was refunded
The "id" parameter is the ID of the transaction
The " type" parameter lets you know this is a "refunded" event
"subscription.created" event
This is an example of the JSON response you will find in the body of the HTTP POST payload:
{
"subscription_id": "rdWQN75zjq",
"customer_id": "Q7zqVMy5Bg",
"status": "active",
"customer_email": "johndoe@example.com",
"plan_name": "Silver Plan",
"product_name": "My Course",
"product_link": "nb7fD",
"gdpr_consent": "Yes",
"date_subscription_started": 1703694529,
"customer_first_name": "John",
"customer_last_name": "Doe",
"type": "subscription.created",
"signature": "dbcdccb0dfc5a57rh704bc75d7bbb18hdd3ee85f4081d5c4adbff934622919d8"
}
The "type" parameter lets you know this is a "subcription.created" event
"subscription.deleted" event
This is an example of the JSON response you will find in the body of the HTTP POST payload:
{
"subscription_id": "rdWQN75zjq",
"customer_id": "Q7zqVMy5Bg",
"status": "canceled",
"customer_email": "johndoe@example.com",
"plan_name": "Silver Plan",
"product_name": "My Course",
"product_link": "nb7fD",
"gdpr_consent": "Yes",
"date_subscription_started": 1703694529,
"date_subscription_deleted": 1703694700,
"customer_first_name": "John",
"customer_last_name": "Doe",
"type": "subscription.deleted",
"signature": "dbcdccb0dfc5a57rh704bc75d7bbb18hdd3ee85f4081d5c4adbff934622919d8"
}
The "type" parameter lets you know this is a "subcription.deleted" event
Key notes
1) Please note, all prices are in cents or pennies. For example, 10 dollars or euros will be represented as 1000.
2) To ensure that the webhook comes from us for security reasons you can use the "signature" property. The signature can be matched by comparing with
hash('sha256', $apiKey)
The above is a PHP snippet, you can use sha256 hashing in any language. Your API key can be found from your Settings > Developer page.