v4

latestOpenAPI 3.1.0MIT2026-08-02128224900.7 KB

Event notification

When an event you've subscribed to occurs, Buttondown sends an HTTP POST to your configured webhook URL. If the webhook has a signing key, the request carries an X-Buttondown-Signature: sha256=<hmac> header — an HMAC-SHA256 of the raw request body keyed with your signing key. Respond with any 2xx status to acknowledge receipt; five consecutive non-2xx responses disable the webhook.

postWebhookevent

Payload

idstring required

The unique TypeID of the event that triggered this delivery.

event_type'advertising_slot.inquiry' | 'advertising_slot.purchased' | 'automation.invoked' | 'date.day.started' | 'date.month.started' | 'date.week.started' | 'date.year.started' | 'bigcommerce.customer.created' | 'bigcommerce.customer.updated' | 'bigcommerce.order.created' | 'bigcommerce.order.updated' | 'email.created' | 'email.deleted' | 'email.sent' | 'email.status.changed' | 'email.updated' | 'external_feed_item.created' | 'export.completed' | 'export.created' | 'export.failed' | 'firewall.blocked' | 'mention.created' | 'memberful.member.updated' | 'memberful.subscription.created' | 'memberful.subscription.deleted' | 'note.created' | 'note.deleted' | 'patreon.member.updated' | 'patreon.membership.created' | 'patreon.membership.deleted' | 'shopify.customer.created' | 'shopify.customer.updated' | 'social_mention.created' | 'stripe.checkout.session.completed' | 'stripe.customer.updated' | 'stripe.invoice.upcoming' | 'stripe.subscription.activated' | 'stripe.subscription.churning' | 'stripe.subscription.deactivated' | 'subscriber.activation_bounced' | 'subscriber.activation_clicked' | 'subscriber.activation_complained' | 'subscriber.activation_deferred' | 'subscriber.activation_delivered' | 'subscriber.activation_opened' | 'subscriber.activation_rejected' | 'subscriber.bounced' | 'subscriber.changed_email' | 'subscriber.churned' | 'subscriber.clicked' | 'subscriber.commented' | 'subscriber.complained' | 'subscriber.confirmed' | 'subscriber.created' | 'subscriber.deferred' | 'subscriber.deleted' | 'subscriber.delivered' | 'subscriber.opened' | 'subscriber.paid' | 'subscriber.paused' | 'subscriber.resumed' | 'subscriber.referred' | 'subscriber.referred.paid' | 'subscriber.rejected' | 'subscriber.replied' | 'subscriber.sent' | 'subscriber.responded_to_survey' | 'subscriber.tags.changed' | 'subscriber.trial_ended' | 'subscriber.trial_started' | 'subscriber.type.changed' | 'subscriber.unsubscribed' | 'subscriber.updated' | 'subscriber.viewed_checkout_page' | 'survey.cleared_responses' | 'survey.created' | 'survey.deleted' | 'survey.updated' | 'form.created' | 'form.deleted' | 'form.updated' required

Various types of events that are recorded by Buttondown, both in terms of exogenous systems like Stripe and Memberful, and endogenous ones like email opens and clicks. (In general, if anything important ever happens that could be relevant to your newsletter, we have an event type for it!)

These event types power lots of things within Buttondown. They're used to trigger automations, webhooks, and analytics.

(Note that Buttondown also has a different thing we call "events"; those are EmailEvents and are used for tracking aggregate details about an email. Alas, we shouldn't have used the term "event" for two different things, but it's too late to go back now!)

In general, our event namespacing tries to hew to the following pattern:

<source>.<object>.<action>

When wondering which object we are referring to, default to the more granular object.

For instance, an email being sent to a subscriber is subscriber.delivered, not email.sent.

dataobject required

Event-specific metadata. The shape varies by event_type. Accounts with more than one newsletter also receive a newsletter ID to disambiguate which one the event belongs to.

Example payload

{
  "id": "ext_evt_00000000000000000000000000"
}

Response

Return any 2xx status to acknowledge the event.