A webhook integration is an HTTPS endpoint QueueUp POSTs JSON events to. Every delivery is HMAC-signed, retried on failure, and recorded with its full attempt history.
This page covers configuring a webhook integration in the panel. For the wire protocol (envelope shape, event catalog, headers, retry policy) see Events & retries. For verification code samples see Verifying webhooks.
Configuration
| Field | Editable | Notes |
|---|---|---|
| Name | Yes | Cosmetic. Shown in the panel and as the binding tab label. |
| URL | Yes (settings) | HTTPS only by default. Rejected at save if it resolves to a private, loopback, or link-local address. |
| Description | Yes | Internal note. |
| Signing secret | Rotate-only | Generated on create, shown once. Use Rotate secret to mint a new one (also shown once). |
| Custom headers | Yes | Up to 10 extra headers sent on every delivery. See below. |
| Paused | Yes | When paused, no deliveries are enqueued for any binding. |
Event scope is not stored on the integration. It’s per-binding (per-waitlist). See Binding it to a waitlist below.
Custom headers
Add static HTTP headers QueueUp will set on every delivery. Useful when your endpoint sits behind an auth proxy (Cloudflare Access, an API gateway, a per-tenant Bearer token, etc.).
Each header is one of:
- Public. Value is stored in plaintext and visible in the panel. Use for routing or tenant-id style headers.
- Secret. Value is encrypted at rest and shown masked in the panel. Use for tokens, API keys, anything you wouldn’t want a teammate to read off the screen. Secret values are write-only: once saved, they’re never returned by the API. Leave the field empty when editing to keep the existing value; type a new value to replace it.
Limits: up to 10 headers per integration, up to 1024 bytes per value.
QueueUp’s own headers always win on collision, so the following names are rejected at save:
Content-Type,Content-Length,Host,User-Agent- Anything starting with
X-QueueUp-
Authorization is allowed; that’s the Bearer-token case.
Sending a test
The detail page has a Send test button. It enqueues a synthetic webhook.ping event targeting only this integration. Use it to confirm:
- Your URL is reachable from QueueUp.
- Your verification logic accepts a real signature.
- Your custom headers are read correctly on your side.
webhook.ping is a special, panel-only event. It bypasses per-waitlist routing entirely, so it always lands at the integration you click the button on, regardless of bindings.
Binding it to a waitlist
A webhook integration sits idle until you bind it. To bind:
- Open the waitlist’s Setup page.
- Scroll to Integrations and click Add.
- Pick the webhook integration from the picker. A new tab opens for the binding.
Each binding has its own event scope. Open the tab and use the Events section to pick which events fire this binding:
- All events (default). Every event QueueUp emits today.
- Pick discrete events. Turn off the All events switch and check the events you want.
Today the bindable webhook events are subscriber.joined and subscriber.confirmed. Full payload reference: Events & retries → Event catalog.
You can bind the same webhook integration to a waitlist multiple times with different event scopes. That’s useful when you want explicit per-event rules: for example, one binding scoped to subscriber.joined and another to subscriber.confirmed. Be aware that overlapping scopes produce duplicate POSTs.
Inspecting deliveries
The detail page shows recent deliveries with status, HTTP code, attempt count, and latency. Click a row for the per-attempt history including response body excerpts and error strings.
Dead deliveries can be re-enqueued with the Redeliver button in the delivery detail dialog. Redelivery creates a fresh row pointing at the same event and runs the full retry budget again.
Rotating the secret
From the settings page, click Rotate secret. The new value is shown once and replaces the old one immediately. There’s no grace period, so any consumer still using the old secret will fail signature verification on the next delivery.
Plan the rotation: pause the integration, update your consumer with the new secret, unpause. Or accept a brief window of dead-lettered deliveries that you can redeliver after your consumer is updated.