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)

​
subscriber.link_click
string

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>" }'