ConvertKit Webhook
Kit (formerly ConvertKit) POSTs JSON when a configured subscriber or purchase automation fires — new subscribers, tag changes, sequence milestones, link clicks, product purchases, and purchase records. Each POST is one stored report; tools read what already landed. There is no pull API and no way to tag, unsubscribe, or replay webhooks from here.
Upstream webhook rules are scoped per event (and often per form, tag, sequence, product, or link). The POST body does not repeat the rule name — use the connection Purpose label, ## This connection notes, or payload shape to infer which automation fired.
First moves
- Latest report — default for “who subscribed”, “what tag fired”, or “what sold last”.
- Classify the payload — export.json.subscriber means a subscriber event; top-level transaction_id or products means a purchase event.
- Recent reports — list when comparing tag volume, sequence completions, duplicate purchases, or funnel activity.
- One report by id — after listing, when the user names a specific delivery.
Configurable event types (upstream)
When wiring the ingest URL in Kit, each webhook rule listens for one event. Common rules teams attach to separate connections or distinct Purpose labels:
| Event name | Fires when | Rule filter (when required) |
|---|
| subscriber.subscriber_activate | Subscriber becomes active | — |
| subscriber.subscriber_unsubscribe | Subscriber unsubscribes | — |
| subscriber.subscriber_bounce | Email bounces | — |
| subscriber.subscriber_complain | Spam complaint | — |
| subscriber.form_subscribe | Subscribes via a form | form_id |
| subscriber.course_subscribe | Enters a sequence | sequence_id |
| subscriber.course_complete | Completes a sequence | sequence_id |
| subscriber.link_click | Clicks a tracked link | initiator_value (URL) |
| subscriber.product_purchase | Purchases a Kit product | product_id |
| subscriber.tag_add | Tag added to subscriber | tag_id |
| subscriber.tag_remove | Tag removed from subscriber | tag_id |
| purchase.purchase_create | A purchase record is created | — |
| custom_field.field_created | Custom field created | — |
| custom_field.field_deleted | Custom field deleted | — |
| custom_field.field_value_updated | Subscriber custom field value changes | custom_field_id |
v3 webhook setup names use the same semantics with a subscriber. prefix on create; stored payloads do not include the event string.
Subscriber event JSON (export.json)
Most lifecycle, tag, form, sequence, and link-click deliveries wrap the person under subscriber:
- subscriber.id — Kit subscriber id (stable dedupe key with email).
- subscriber.email_address — contact email.
- subscriber.first_name — when collected.
- subscriber.state — e.g. active, inactive, cancelled (exact values depend on account settings).
- subscriber.created_at — ISO 8601 when the subscriber record was created in Kit.
- subscriber.fields — object map of custom field labels to values (keys mirror field names in the Kit UI, e.g. "My Custom Field": "Value").
Use this block for activate, unsubscribe, bounce, complain, form subscribe, sequence subscribe/complete, tag add/remove, link click, and product-purchase subscriber hooks. Tag and sequence rules fire with the same subscriber shape — the webhook rule (not the JSON) carries which tag_id, sequence_id, form_id, product_id, or link URL matched.
Purchase event JSON (export.json)
purchase.purchase_create and some commerce flows POST a flat purchase object (no subscriber wrapper):
- id — Kit purchase id.
- transaction_id — external or Kit transaction reference; primary dedupe key alongside email.
- status — e.g. paid.
- email_address — buyer email.
- currency — ISO currency code (may be uppercase in payloads, e.g. JPY).
- transaction_time — ISO 8601 purchase time; prefer over source.captured_at for revenue timing.
- subtotal, tax, shipping, discount, total — monetary components when present.
- products — array of line items, each with name, sku, quantity, unit_price when supplied.
Response shape
- export.json — parsed webhook body (start here for subscriber and purchase questions).
- export.text — raw body when JSON is large or non-object.
- source.captured_at — when the POST landed here (may lag transaction_time or list activity).
Operational order
- Start with the latest report — do not guess a report id.
- Decide subscriber vs purchase shape before quoting revenue or tags.
- If captured_at is older than expected, say so — events arrive only when Kit fires the matching rule.
- List recent reports only for history, duplicate suspicion, or explicit compare-by-date asks.
- Read ## This connection in the skill supplement for which tag, form, sequence, or product this URL listens to.
Gotchas
- Read-only — cannot add tags, enroll sequences, create purchases, or replay Kit webhooks from here.
- No event name in body — infer from payload shape plus connection Purpose / supplement notes; do not invent tag_add vs subscriber_activate without context.
- One rule per URL — separate webhooks for separate tags or sequences; one connection may still receive mixed shapes if multiple rules point at the same ingest URL.
- Subscriber vs purchase — tag and sequence events use the subscriber object; purchase.purchase_create uses the flat purchase schema — do not expect subscriber on every delivery.
- Custom fields are label-keyed — subscriber.fields keys match Kit field names, not internal ids; spelling and spacing matter.
- Product purchase hooks — subscriber.product_purchase rules filter by product id upstream; the JSON still looks like a subscriber payload.
- Duplicates — compare subscriber.id, transaction_id, and source.captured_at when the upstream retries the same event.
- Empty — no stored reports means nothing has arrived yet; say no webhook is available.
