Gumroad Webhook

Gumroad Webhook

Gumroad Ping posts purchase and refund notifications as application/x-www-form-urlencoded form fields. Storage normalizes each POST to flat JSON in export.json. Nested objects — variants, custom_fields, url_params, shipping_information, and card — arrive as bracketed keys (for example custom_fields[name]) and appear as nested objects after normalization. Tools read what already landed; there is no way to trigger a new ping or change Gumroad state from here.

First moves

1. Latest report — default for “who bought what last” or the most recent refund signal.
2. Recent reports — compare volume, spot duplicate pings, or find a sale by buyer email or product name.
3. Inspect export.json — all Ping fields live here; use source.captured_at for when the ping landed, not necessarily when the sale occurred (sale_timestamp is inside the payload).
4. One report by id — after listing, when the user points at a specific delivery.

Key payload fields

Read these from export.json rather than assuming fixed column names:

• Event kind — resource_name: sale for a purchase, refund when that purchase is later refunded. Always pair with sale_id when deduping — a refund reuses the same sale_id as its sale.
• Sale identity — sale_id, order_number (numeric form of sale_id), sale_timestamp.
• Product — product_id, product_name, product_permalink, short_product_id.
• Buyer — email, full_name when present, purchaser_id when the buyer has a Gumroad account, ip_country.
• Money — price in USD cents; also shipping_rate, gumroad_fee, gift_price, and affiliate_credit_amount_cents when relevant. Divide by 100 for dollar amounts unless the user asked for cents.
• Subscription — subscription_id, recurrence (for example monthly, yearly, quarterly), is_recurring_charge.
• Options and extras — variants (selected tier/size/color), custom_fields, offer_code, license_key, quantity.
• Marketing — url_params (tracking params from the product link), affiliate, referrer.
• Gift purchases — is_gift_receiver_purchase, gifter_email, gift_price.
• Status flags — refunded, test (seller self-purchase), disputed, dispute_won, is_preorder_authorization, discover_fee_charged.
• Retries — retry_count (1, 2, or 3) when Gumroad redelivered after a failed attempt.

Response shape

• source — capture time, filename, format, connection purpose.
• export.json — normalized Ping fields from the urlencoded POST body.
• export.text — raw body when JSON parsing did not apply.

Operational order

1. Start with the latest report — do not guess a report id.
2. Check resource_name and sale_id before treating a ping as a new sale.
3. If captured_at is older than expected, say so — Gumroad sends on purchase/refund events, not on demand.
4. List recent reports only for history, duplicate suspicion, or explicit compare-by-date asks.
5. Read ## This connection in the skill supplement for product-specific field notes.

Gotchas

• Read-only — cannot refund, resend pings, or acknowledge Gumroad from here.
• At-least-once delivery — the same ping can arrive more than once; dedupe on sale_id plus resource_name, not sale_id alone.
• Ordering not guaranteed — a refund ping can land before the sale ping it refers to; list recent deliveries when the user asks about refunds.
• Retries — failed upstream delivery retries with retry_count set; duplicates may share the same sale data with different source.captured_at.
• Unsigned payloads — treat stored pings as notifications to inspect, not as authoritative ledger entries when amounts or refund state matter critically.
• Variable presence — variants, custom_fields, shipping_information, license_key, and subscription fields appear only for relevant products; absence is normal.
• Test purchases — test is true when the seller bought their own product.