Resource Subscriptions

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

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

boolean

Whether the request was successful

array

Array of resource subscription objects

Show resource_subscription properties

string

Unique identifier for the resource subscription

string

The type of event this subscription listens for

string

The webhook URL where notifications will be sent via POST request

curl "https://api.gumroad.com/v2/resource_subscriptions?resource_name=sale" \
  -H "Authorization: Bearer <access_token>"

{
  "success": true,
  "resource_subscriptions": [
    {
      "id": "sub_abc123",
      "resource_name": "sale",
      "post_url": "https://example.com/webhooks/gumroad"
    },
    {
      "id": "sub_def456",
      "resource_name": "sale",
      "post_url": "https://another-service.com/gumroad-webhook"
    }
  ]
}

Create Resource Subscription

Subscribe to webhook notifications for a specific resource type.

PUT /v2/resource_subscriptions

Body Parameters

string

required

The resource type to subscribe to. Must be one of: sale, refund, cancellation, subscription_ended, subscription_restarted, subscription_updated, dispute, dispute_won

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

boolean

Whether the request was successful

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"

{
  "success": true,
  "resource_subscription": {
    "id": "sub_abc123",
    "resource_name": "sale",
    "post_url": "https://example.com/webhooks/gumroad"
  }
}

Delete Resource Subscription

Unsubscribe from webhook notifications.

DELETE /v2/resource_subscriptions/:id

Path Parameters

string

required

The unique identifier of the resource subscription to delete

Response

boolean

Whether the request was successful

curl -X DELETE https://api.gumroad.com/v2/resource_subscriptions/sub_abc123 \
  -H "Authorization: Bearer <access_token>"

{
  "success": true
}

Webhook Payload

When an event occurs, Gumroad will send a POST request to your post_url with the following structure:

string

Your Gumroad user ID

string

The product ID related to the event

string

The name of the product

string

The product permalink

string

The full product URL

string

The unique sale ID

string

ISO 8601 timestamp of the sale

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": "customer@example.com",
  "price": "2999",
  "currency": "usd",
  "quantity": "1",
  "purchaser_id": "1234567890",
  "subscription_id": null
}

Webhook Security

Gumroad webhooks are secured in the following ways:

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

Testing Webhooks

To test your webhook integration:

Create a resource subscription pointing to your test URL
Make a test purchase using a test payment method
Verify your endpoint receives the webhook POST request
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

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

Unauthorized - Invalid or missing access token

Forbidden - Insufficient permissions (requires view_sales scope)

Not Found - Resource subscription not found or doesn’t belong to your OAuth application

Unprocessable Entity - Unable to create subscription with the provided parameters

Getting Started

Products

Sales

Licenses

Subscribers

Other Resources

Resource Subscriptions

Available Resources

List Resource Subscriptions

Query Parameters

Response

Create Resource Subscription

Body Parameters

Response

Delete Resource Subscription

Path Parameters

Response

Webhook Payload

Example Webhook Payload

Webhook Security

Testing Webhooks

Error Codes

​Available Resources

​List Resource Subscriptions

​Query Parameters

​Response

​Create Resource Subscription

​Body Parameters

​Response

​Delete Resource Subscription

​Path Parameters

​Response

​Webhook Payload

​Example Webhook Payload

​Webhook Security

​Testing Webhooks

​Error Codes

Available Resources

List Resource Subscriptions

Query Parameters

Response

Create Resource Subscription

Body Parameters

Response

Delete Resource Subscription

Path Parameters

Response

Webhook Payload

Example Webhook Payload

Webhook Security

Testing Webhooks

Error Codes