> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Webhooks v3 endpoints

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

```json theme={null}
{
  "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

```json theme={null}
{
    "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

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="target_url" type="string" required={true}>
  The URL that will receive subscriber data when the event is triggered
</ParamField>

<ParamField path="event" type="object" required={true}>
  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)
</ParamField>

### Available Event Types

<ParamField path="subscriber.subscriber_activate" type="string">
  Triggered when a subscriber is activated
</ParamField>

<ParamField path="subscriber.subscriber_unsubscribe" type="string">
  Triggered when a subscriber unsubscribes
</ParamField>

<ParamField path="subscriber.subscriber_bounce" type="string">
  Triggered when a subscriber email bounces
</ParamField>

<ParamField path="subscriber.subscriber_complain" type="string">
  Triggered when a subscriber complains
</ParamField>

<ParamField path="subscriber.form_subscribe" type="string">
  Triggered when a subscriber subscribes to a form. **Required parameter**: `form_id` (Integer)
</ParamField>

<ParamField path="subscriber.course_subscribe" type="string">
  Triggered when a subscriber subscribes to a sequence. **Required parameter**: `sequence_id` (Integer)
</ParamField>

<ParamField path="subscriber.course_complete" type="string">
  Triggered when a subscriber completes a sequence. **Required parameter**: `sequence_id` (Integer)
</ParamField>

<ParamField path="subscriber.link_click" type="string">
  Triggered when a subscriber clicks a link. **Required parameter**: `initiator_value` (String) as a link URL
</ParamField>

<ParamField path="subscriber.product_purchase" type="string">
  Triggered when a subscriber purchases a product. **Required parameter**: `product_id` (Integer)
</ParamField>

<ParamField path="subscriber.tag_add" type="string">
  Triggered when a tag is added to a subscriber. **Required parameter**: `tag_id` (Integer)
</ParamField>

<ParamField path="subscriber.tag_remove" type="string">
  Triggered when a tag is removed from a subscriber. **Required parameter**: `tag_id` (Integer)
</ParamField>

<ParamField path="purchase.purchase_create" type="string">
  Triggered when a purchase is created
</ParamField>

<CodeGroup>
  ```shell Request (Subscriber Activate) theme={null}
  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" } }'
  ```

  ```shell Request (Sequence Complete) theme={null}
  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 } }'
  ```

  ```json Response (Subscriber Activate) theme={null}
  {
    "rule": {
      "id": 1,
      "account_id": 2,
      "event": {
        "name": "subscriber_activate"
      }
    }
  }
  ```

  ```json Response (Sequence Complete) theme={null}
  {
    "rule": {
      "id": 43,
      "account_id": 2,
      "event": {
        "name": "course_complete",
        "sequence_id": 18
      },
      "target_url": "http://example.com/"
    }
  }
  ```
</CodeGroup>

## Destroy webhook

Permanently delete a webhook automation.

### Endpoint

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

### Parameters

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="rule_id" type="integer" required={true}>
  The ID of the webhook rule you want to delete
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  curl -X DELETE https://api.convertkit.com/v3/automations/hooks/<rule_id>\
       -H 'Content-Type: application/json'\
       -d '{ "api_secret": "<your_secret_api_key>" }'
  ```

  ```json Response theme={null}
  {
    "success": true
  }
  ```
</CodeGroup>