Skip to main content
Resource subscriptions allow you to receive webhook notifications when specific events occur in your Gumroad account. This is useful for integrating Gumroad with external services.
Resource subscriptions require the view_sales scope. Each subscription is tied to a specific OAuth application.

​
Available Resources

You can subscribe to the following resource types:
  • sale - New sale completed
  • refund - Sale refunded
  • cancellation - Subscription cancelled by customer
  • subscription_ended - Subscription ended (all billing cycles complete)
  • subscription_restarted - Cancelled subscription restarted
  • subscription_updated - Subscription plan or payment method updated
  • dispute - Payment dispute opened
  • dispute_won - Payment dispute resolved in your favor

​
List Resource Subscriptions

Retrieve all active resource subscriptions for a specific resource type. 
GET /v2/resource_subscriptions?resource_name=:resource_name

​
Query Parameters

​
resource_name
string
required
The resource type to filter by. Must be one of: sale, refund, cancellation, subscription_ended, subscription_restarted, subscription_updated, dispute, dispute_won

​
Response

​
success
boolean
Whether the request was successful
​
resource_subscriptions
array
Array of resource subscription objects
curl "https://api.gumroad.com/v2/resource_subscriptions?resource_name=sale" \
  -H "Authorization: Bearer <access_token>"

​
Create Resource Subscription

Subscribe to webhook notifications for a specific resource type. 
PUT /v2/resource_subscriptions

​
Body Parameters

​
resource_name
string
required
The resource type to subscribe to. Must be one of: sale, refund, cancellation, subscription_ended, subscription_restarted, subscription_updated, dispute, dispute_won
​
post_url
string
required
The webhook URL where notifications will be sent. Must be a valid HTTPS or HTTP URL. Cannot use localhost, 127.0.0.1, or 0.0.0.0.

​
Response

​
success
boolean
Whether the request was successful
​
resource_subscription
object
The created resource subscription object
curl -X PUT https://api.gumroad.com/v2/resource_subscriptions \
  -H "Authorization: Bearer <access_token>" \
  -d "resource_name=sale" \
  -d "post_url=https://example.com/webhooks/gumroad"

​
Delete Resource Subscription

Unsubscribe from webhook notifications. 
DELETE /v2/resource_subscriptions/:id

​
Path Parameters

​
id
string
required
The unique identifier of the resource subscription to delete

​
Response

​
success
boolean
Whether the request was successful
curl -X DELETE https://api.gumroad.com/v2/resource_subscriptions/sub_abc123 \
  -H "Authorization: Bearer <access_token>"

​
Webhook Payload

When an event occurs, Gumroad will send a POST request to your post_url with the following structure:
​
seller_id
string
Your Gumroad user ID
​
product_id
string
The product ID related to the event
​
product_name
string
The name of the product
​
permalink
string
The product permalink
​
product_permalink
string
The full product URL
​
sale_id
string
The unique sale ID
​
sale_timestamp
string
ISO 8601 timestamp of the sale
​
...additional fields
Additional fields vary by resource type and match the sale object structure

​
Example Webhook Payload

{
  "seller_id": "user_123",
  "product_id": "prod_abc",
  "product_name": "My eBook",
  "permalink": "my-ebook",
  "product_permalink": "https://example.gumroad.com/l/my-ebook",
  "sale_id": "sale_xyz789",
  "sale_timestamp": "2024-03-15T14:30:00Z",
  "email": "[email protected]",
  "price": "2999",
  "currency": "usd",
  "quantity": "1",
  "purchaser_id": "1234567890",
  "subscription_id": null
}

​
Webhook Security

Gumroad webhooks are secured in the following ways:
  1. HTTPS: Use HTTPS URLs when possible to encrypt webhook data in transit
  2. Verification: Verify webhook requests by making a GET request to the sale API endpoint to confirm the sale exists
  3. IP Allowlisting: Consider allowlisting Gumroad’s IP addresses if your firewall supports it

​
Testing Webhooks

To test your webhook integration:
  1. Create a resource subscription pointing to your test URL
  2. Make a test purchase using a test payment method
  3. Verify your endpoint receives the webhook POST request
  4. Return a 200 status code to acknowledge receipt
Gumroad will retry failed webhook deliveries with exponential backoff. If your endpoint consistently fails to respond with a 2xx status code, the subscription may be automatically disabled.

​
Error Codes

​
400
Bad Request - Invalid post_url (must be valid HTTP/HTTPS URL, cannot be localhost/127.0.0.1/0.0.0.0) or invalid resource_name
​
401
Unauthorized - Invalid or missing access token
​
403
Forbidden - Insufficient permissions (requires view_sales scope)
​
404
Not Found - Resource subscription not found or doesn’t belong to your OAuth application
​
422
Unprocessable Entity - Unable to create subscription with the provided parameters

Build docs developers (and LLMs) love

Get started for freeTalk to us