Webhooks are automations that will receive subscriber data when a subscriber event is triggered, such as when a subscriber completes a sequence. When a webhook is triggered, a POST request will be made to your URL with a JSON payload.

Example Payloads

Subscriber Event Payload

{
  "subscriber": {
    "id": 1,
    "first_name": "John",
    "email_address": "[email protected]",
    "state": "active",
    "created_at": "2018-02-15T19:40:24.913Z",
    "fields": {
      "My Custom Field": "Value"
    }
  }
}

Purchase Event Payload

{
    "id": 8,
    "transaction_id": "123-abcd-456-efgh",
    "status": "paid",
    "email_address": "[email protected]",
    "currency": "JPY",
    "transaction_time": "2018-03-17T11:28:04Z",
    "subtotal": 20.0,
    "shipping": 2.0,
    "discount": 3.0,
    "tax": 2.0,
    "total": 21.0,
    "products": [
        {
            "unit_price": 5.0,
            "quantity": 2,
            "sku": "7890-ijkl",
            "name": "Floppy Disk (512k)"
        },
        {
            "unit_price": 10.0,
            "quantity": 1,
            "sku": "mnop-1234",
            "name": "Telephone Cord (data)"
        }
    ]
}

Create a webhook

Create a webhook that will be called when a subscriber event occurs.

Endpoint

POST /v3/automations/hooks

Parameters

api_secret
string
required
Your API secret key
target_url
string
required
The URL that will receive subscriber data when the event is triggered
event
object
required
JSON object that includes the trigger name and extra information when needed. Must include:
  • name (required): The event type name
  • Additional parameters may be required based on the event type (see Available Event Types below)

Available Event Types

subscriber.subscriber_activate
string
Triggered when a subscriber is activated
subscriber.subscriber_unsubscribe
string
Triggered when a subscriber unsubscribes
subscriber.subscriber_bounce
string
Triggered when a subscriber email bounces
subscriber.subscriber_complain
string
Triggered when a subscriber complains
subscriber.form_subscribe
string
Triggered when a subscriber subscribes to a form. Required parameter: form_id (Integer)
subscriber.course_subscribe
string
Triggered when a subscriber subscribes to a sequence. Required parameter: sequence_id (Integer)
subscriber.course_complete
string
Triggered when a subscriber completes a sequence. Required parameter: sequence_id (Integer)
Triggered when a subscriber clicks a link. Required parameter: initiator_value (String) as a link URL
subscriber.product_purchase
string
Triggered when a subscriber purchases a product. Required parameter: product_id (Integer)
subscriber.tag_add
string
Triggered when a tag is added to a subscriber. Required parameter: tag_id (Integer)
subscriber.tag_remove
string
Triggered when a tag is removed from a subscriber. Required parameter: tag_id (Integer)
purchase.purchase_create
string
Triggered when a purchase is created
curl -X POST https://api.convertkit.com/v3/automations/hooks\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>",
           "target_url": "http://example.com/incoming",
           "event": { "name": "subscriber.subscriber_activate" } }'

Destroy webhook

Permanently delete a webhook automation.

Endpoint

DELETE /v3/automations/hooks/#{rule_id}

Parameters

api_secret
string
required
Your API secret key
rule_id
integer
required
The ID of the webhook rule you want to delete
curl -X DELETE https://api.convertkit.com/v3/automations/hooks/<rule_id>\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>" }'