Kit Developer Documentation

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

Triggered when a subscriber subscribes to a form. Required parameter: form_id (Integer)

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

On this page

Example Payloads
Subscriber Event Payload
Purchase Event Payload
Create a webhook
Endpoint
Parameters
Available Event Types
Destroy webhook
Endpoint
Parameters

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

Triggered when a subscriber subscribes to a form. Required parameter: form_id (Integer)

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

On this page

Example Payloads
Subscriber Event Payload
Purchase Event Payload
Create a webhook
Endpoint
Parameters
Available Event Types
Destroy webhook
Endpoint
Parameters

Webhooks

Example Payloads

Subscriber Event Payload

Purchase Event Payload

Create a webhook

Endpoint

Parameters

Available Event Types

Destroy webhook

Endpoint

Parameters

Getting started

Guides

Endpoints

Webhooks

Example Payloads

Subscriber Event Payload

Purchase Event Payload

Create a webhook

Endpoint

Parameters

Available Event Types

Destroy webhook

Endpoint

Parameters

​Example Payloads

​Subscriber Event Payload

​Purchase Event Payload

​Create a webhook

​Endpoint

​Parameters

​Available Event Types

​Destroy webhook

​Endpoint

​Parameters

Getting started

Guides

Endpoints

​Example Payloads

​Subscriber Event Payload

​Purchase Event Payload

​Create a webhook

​Endpoint

​Parameters

​Available Event Types

​Destroy webhook

​Endpoint

​Parameters

Example Payloads

Subscriber Event Payload

Purchase Event Payload

Create a webhook

Endpoint

Parameters

Available Event Types

Destroy webhook

Endpoint

Parameters

Example Payloads

Subscriber Event Payload

Purchase Event Payload

Create a webhook

Endpoint

Parameters

Available Event Types

Destroy webhook

Endpoint

Parameters