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": "John@example.com",
    "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": "crashoverride@hackers.com",
    "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

string

required

Your API secret key

string

required

The URL that will receive subscriber data when the event is triggered

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

string

Triggered when a subscriber is activated

string

Triggered when a subscriber unsubscribes

string

Triggered when a subscriber email bounces

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)

string

Triggered when a subscriber completes a sequence. Required parameter: sequence_id (Integer)

string

Triggered when a subscriber clicks a link. Required parameter: initiator_value (String) as a link URL

string

Triggered when a subscriber purchases a product. Required parameter: product_id (Integer)

string

Triggered when a tag is added to a subscriber. Required parameter: tag_id (Integer)

string

Triggered when a tag is removed from a subscriber. Required parameter: tag_id (Integer)

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

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.course_complete", "sequence_id": 18 } }'

{
  "rule": {
    "id": 1,
    "account_id": 2,
    "event": {
      "name": "subscriber_activate"
    }
  }
}

{
  "rule": {
    "id": 43,
    "account_id": 2,
    "event": {
      "name": "course_complete",
      "sequence_id": 18
    },
    "target_url": "http://example.com/"
  }
}

Destroy webhook

Permanently delete a webhook automation.

Endpoint

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

Parameters

string

required

Your API secret key

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

{
  "success": true
}

Getting Started

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

Example Payloads

Subscriber Event Payload

Purchase Event Payload

Create a webhook

Endpoint

Parameters

Available Event Types

Destroy webhook

Endpoint

Parameters