Webhook drains

Webhook drains

A drain sends collection or view records to an external HTTPS endpoint. You can choose the body format, compression, headers, and whether to include existing records. A project can have up to 10 drains.

Set up a drain

  1. Open project Settings, then Drains.
  2. Click the plus button. The drawer is titled New drain.
  3. Select a collection or view, then provide a name, destination URL, optional headers, body format, compression, delivery schedule, and whether to backfill historical data.
  4. Create the drain.
  5. In Details, click Send verification. Find the tailglow_verify value at your endpoint and paste it back.
  6. The verified drain is paused. Use Send sample on its Activity tab if useful, then click Resume to begin delivery.

A sample sends the latest five eligible records with X-Tailglow-Test: true. It does not advance the drain cursor.

Schedule

Choose how often the drain looks for new records: every minute, every 5 or 15 minutes, hourly, daily, or a custom cron expression. Schedules are evaluated in UTC, and new drains default to hourly. You can change the schedule at any time.

The schedule sets how quickly new records are picked up, not how fast a backlog clears. A drain that has fallen behind keeps sending until it catches up instead of waiting for its next run, so a large backfill is never limited by the schedule you choose.

A run that finds nothing to send makes no request, so a fast schedule adds no traffic to a quiet endpoint. It does change the shape of steady traffic: a drain receiving around 10 records a minute sends roughly 1,440 small requests a day on a per-minute schedule, against 24 larger ones on an hourly schedule. Choose whichever suits your destination.

Batches and retries

Each delivery contains at most 5,000 records and at most 5 MiB of uncompressed serialized data, except that a single oversize record is sent on its own. X-Tailglow-Batch-Id is stable for retries of the same batch, so receivers should use it as an idempotency key.

The cursor advances only after a successful 2xx response. Tailglow retries failures, warns team owners after six hours of continuous failure, and disables the drain after 72 hours. Resume it yourself once the destination is reachable again.

Backfill

With Backfill historical data off, the drain starts from records arriving after its first activation. With it on, the drain catches up existing records before continuing with new ones. This choice cannot be changed after creation.

Draining to Tailglow

Point a drain at the destination project’s copied ingest endpoint and provide a destination ingest key. A trusted destination in the same project can skip marker verification, but two projects owned by the same team do not automatically verify each other. For a non-trusted destination, find the verification marker in the destination collection’s Records tab and confirm it in the drain drawer.

Security

Destinations must be public HTTPS addresses. Tailglow revalidates outbound addresses, rejects private and loopback targets, and times out each request after 30 seconds.