Webhook

Webhooks are used to notify external services of events that occur in the system. For example, when a newsletter is sent, a webhook can be used to notify an external service that the newsletter has been sent.

Basic webhook

{
    "creation_date": "2019-08-24T14:15:22Z",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "url": "https://example.com",
    "description": "Register in remote database every time we get a new subscriber",
    "event": "subscriber.created"
}

field	type	description
id	string
creation_date	string
event_type	ExternalEventType
url	string
description	string

Create Webhook

curl

python

ruby

typescript

Copy to clipboard

import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}

BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/webhooks"

response = requests.post(f"{BASE_URL}{ENDPOINT}", headers=headers)

Parameters

parameter	type	description	optional
event_type
url	string
description	string

Responses

Status	Description	Sample Response
201	Created	{ "creation_date": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "url": "https://example.com", "description": "Register in remote database every time we get a new subscriber", "event": "subscriber.created" }
400	Bad Request	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

Status

Description

Sample Response

201

Created

{
    "creation_date": "2019-08-24T14:15:22Z",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "url": "https://example.com",
    "description": "Register in remote database every time we get a new subscriber",
    "event": "subscriber.created"
}

400

Bad Request

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

403

Forbidden

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

List Webhooks

curl

python

ruby

typescript

Copy to clipboard

import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}

BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/webhooks"

response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)

Responses

Status	Description	Sample Response
200	OK	{ "results": [ { "creation_date": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "url": "https://example.com", "description": "Register in remote database every time we get a new subscriber", "event": "subscriber.created" } ], "count": 1 }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

Status

Description

Sample Response

200

{
    "results": [
        {
            "creation_date": "2019-08-24T14:15:22Z",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "url": "https://example.com",
            "description": "Register in remote database every time we get a new subscriber",
            "event": "subscriber.created"
        }
    ],
    "count": 1
}

403

Forbidden

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

Retrieve Webhook

curl

python

ruby

typescript

Copy to clipboard

import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}

BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/webhooks/{pk}"

response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)

Responses

Status	Description	Sample Response
200	OK	{ "creation_date": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "url": "https://example.com", "description": "Register in remote database every time we get a new subscriber", "event": "subscriber.created" }
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
404	Not Found	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

Status

Description

Sample Response

200

{
    "creation_date": "2019-08-24T14:15:22Z",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "url": "https://example.com",
    "description": "Register in remote database every time we get a new subscriber",
    "event": "subscriber.created"
}

403

Forbidden

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

404

Not Found

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

Update Webhook

curl

python

ruby

typescript

Copy to clipboard

import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}

BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/webhooks/{pk}"

response = requests.patch(f"{BASE_URL}{ENDPOINT}", headers=headers)

Parameters

parameter	type	description	optional
event_type
url	string
description	string

Responses

Status	Description	Sample Response
200	OK	{ "creation_date": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "url": "https://example.com", "description": "Register in remote database every time we get a new subscriber", "event": "subscriber.created" }
400	Bad Request	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

Status

Description

Sample Response

200

{
    "creation_date": "2019-08-24T14:15:22Z",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "url": "https://example.com",
    "description": "Register in remote database every time we get a new subscriber",
    "event": "subscriber.created"
}

400

Bad Request

{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

Delete Webhook

curl

python

ruby

typescript

Copy to clipboard

import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}

BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/webhooks/{pk}"

response = requests.delete(f"{BASE_URL}{ENDPOINT}", headers=headers)

Responses

Status	Description	Sample Response
204	No Content	{}
403	Forbidden	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }
404	Not Found	{ "code": "something_went_wrong", "detail": "Your call is very important to us." }

On this page

The object

Endpoints

/webhooks

/webhooks/{pk}