# Webhooks

Category: [Team, Settings & Integrations](https://basecomp.io/help/settings)
Updated: 2026-11-15

> Webhooks send a signed JSON message to your URL when orders complete, winners are drawn, prizes ship and more. Set them up in Settings > Webhooks.

A webhook tells another system the moment something happens in your store, such as an order completing or a winner being drawn. Add one in [Settings > Webhooks](https://basecomp.io/dashboard/go/settings/webhooks): give Basecomp a URL and pick the events, and it sends a signed JSON message to that URL each time one of them happens.

Don't see **Webhooks** in your sidebar? Add the **Developer tools** app from [Apps](https://basecomp.io/dashboard/go/apps). See [Adding and removing apps](https://basecomp.io/help/getting-started/adding-and-removing-apps).

Use webhooks to connect tools like Zapier or Make, your own server, or a Discord channel.

### Creating a webhook

- Go to **Settings > Webhooks** and click **Create Webhook**. A panel opens.

- Give it a **Name** you will recognise.

- Enter the **Endpoint URL**. It must be HTTPS.

- Tick the **Events** to send. At least one is required.

- Leave **Status** on **Active** and click **Create webhook**. You land on the new webhook's page, with its signing secret and a **Send test** button.

[Image: The Create webhook form with the name, endpoint URL and event checkboxes grouped by orders, customers and competitions]

### Events you can subscribe to

- **Orders**: Order completed, Order refunded.

- **Customers**: Customer created, Customer updated, Customer deleted, Marketing consent updated, Customer tagged, Customer untagged.

- **Competitions**: Winner selected, Prize claimed, Prize shipped, Competition published, Competition unpublished, Competition ending soon, Live draw revealed.

**Competition ending soon** fires a set number of hours before each competition ends. Set it under **Ending soon timing** on the webhook's edit page: **Hours before end**, from 0 to 168. It applies to every competition in your store, and 0 turns it off.

### Sending to Discord

Paste a Discord webhook URL as the endpoint and Basecomp posts a formatted message to that channel instead of raw JSON. This is an easy way to get a team channel alert for every order or winner.

### What Basecomp sends

Each delivery is an HTTPS POST with a JSON body containing an **id**, the **event** name, **created_at**, a **test** flag and a **data** object with the record, such as the order or the winner.

The request carries these headers:

- **X-Webhook-Id**: the delivery's id.

- **X-Webhook-Event**: the event name, for example order.completed.

- **X-Webhook-Signature**: the signature, in the form t=timestamp,v1=signature.

### Verifying the signature

Open the webhook's edit page to find its **Signing secret**. You can show it or **Copy** it. To check a delivery really came from Basecomp:

- Read t (a Unix timestamp) and v1 from the **X-Webhook-Signature** header.

- Build the string timestamp, a full stop, then the raw request body exactly as received.

- Compute an HMAC-SHA256 of that string with your signing secret, as lowercase hex.

- Compare it to v1 using a constant-time comparison, and reject requests whose timestamp is more than 5 minutes old.

If the secret may have leaked, click **Rotate secret**. Deliveries fail verification on your endpoint until you update the secret there too.

### Testing

On the webhook's edit page, **Send a test event** sends a real, signed test delivery for any event you have subscribed to. Pick the **Event** and click **Send test**. You see the response code your endpoint returned. Test deliveries have the test flag set to true.

**Recent deliveries** lists the last 25 attempts to reach the endpoint (and [Activity > API & webhooks](https://basecomp.io/dashboard/go/activity/api) lists the latest deliveries from all your endpoints together), with each one's status (**Pending**, **Retrying**, **Delivered**, **Failed** or **Skipped**) and the request and response.

### Retries and auto-pause

Your endpoint should answer with any 2xx status to confirm it received the delivery. If it does not:

- Basecomp makes up to 5 attempts in total, waiting longer after each failure (about a minute at first, rising to 30 minutes).

- A 404 or 410 response is treated as permanent and is not retried.

- A 429 (rate limited) response is retried later without using up an attempt.

If 10 deliveries in a row fail, Basecomp pauses the webhook by setting it to **Inactive**, and the team members who receive the "Webhook auto-paused" notification are emailed. Fix the endpoint, then edit the webhook and set **Status** back to **Active**.

### Who can manage webhooks

Team members need **Edit Settings**.

### See also

- [API keys](https://basecomp.io/help/settings/api-keys)

- [Integrations](https://basecomp.io/help/settings/integrations)

- [Notifications](https://basecomp.io/help/settings/notifications)

- [Managing winners](https://basecomp.io/help/prizes-and-winners/managing-winners)
