What is webhook?

A webhook allows third-party services to send real-time updates to your app. Updates are triggered by some event or action by the webhook provider and pushed to your app via HTTP requests. When you receive the request, you handle it with some custom logic, like sending an email or storing the data in a database.

Buy Me a Coffee utilizes webhooks to inform your application of events occurring within your account. This enables creators to automate certain actions based on events, for e.g; when someone buys them a coffee or when someone subscribes to their membership.

Create a webhook

Go to Integrations in your creator dashboard.
Click New webhook.
Enter a Webhook name to help identify it later.
Enter your Endpoint URL.
Under Add events, select the events you want to receive.
Click Save.

Enable or disable a webhook

The webhook can be enabled or disabled at any time using the Delivery status toggle on the webhook details page.

Note: If more than 10 consecutive deliveries fail, the webhook is automatically disabled and an email notification is sent to you.

Signing secret

Each webhook has a unique Signing Secret used to verify that incoming webhook requests were sent by Buy Me a Coffee.

You can find the signing secret on the webhook details page.

Important: Rolling the signing secret immediately invalidates the previous secret. Update your application before generating a new one.

Verify webhook signatures

Every webhook request includes the following header:

x-signature-sha256

To verify the request:

Read the raw request body exactly as received.
Generate an HMAC-SHA256 hash using:
- the raw request body as the message
- your signing secret as the key
Compare the generated hash with the value in the x-signature-sha256 header.
If both values match, the request is authentic.

Example (Node.js)

const crypto = require('crypto');

function verifySignature(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Send a test event

Open the webhook details page.
Click Send test event.
Select an event type.
Review the request preview.
Click Send test.

Edit a webhook

Open the three-dot menu on the webhook details page and click Edit.

You can update:

Webhook name
Endpoint URL
Subscribed events

Delete a webhook

Open the three-dot menu and click Delete.

Warning: Deleting a webhook is permanent and cannot be undone.

Event deliveries

The Event deliveries section displays every delivery attempt for the webhook.

Click any delivery to view:

Complete request payload
Response returned by your endpoint

Retry behavior

Failed webhook deliveries are retried automatically up to 4 additional times using exponential delays:

Supported event types

Event	Trigger
`donation.created`	A supporter makes a one-time donation
`donation.refunded`	A one-time donation is refunded
`extra_purchase.created`	A shop item is purchased
`extra_purchase.updated`	A shop order is updated
`extra_purchase.refunded`	A shop order is refunded
`commission_order.created`	A commission order is placed
`commission_order.refunded`	A commission order is refunded
`wishlist_payment.created`	A wishlist item receives funding
`wishlist_payment.refunded`	A wishlist payment is refunded
`membership.started`	A membership subscription begins
`membership.updated`	A membership subscription is updated
`membership.cancelled`	A membership subscription is cancelled
`membership.paused`	A membership subscription is paused
`recurring_donation.started`	A monthly support begins
`recurring_donation.updated`	A monthly support is updated
`recurring_donation.cancelled`	A monthly support is cancelled

Webhook payload structure

Every webhook event follows the same outer structure.

{
  "event_id": 1234,
  "type": "donation.created",
  "live_mode": true,
  "created": 1719825600,
  "attempt": 1,
  "data": {}
}

Field	Description
`event_id`	Unique identifier for the delivery
`type`	Event type
`live_mode`	`false` for dashboard test events, otherwise `true`
`created`	Unix timestamp when the event was created
`attempt`	Current delivery attempt number
`data`	Event-specific payload