# Firehose

> Receive every new episode from your chosen shows as signed batches, in order: the payload, retries, replays and testing.

A firehose is a URL of yours that Podzone POSTs every new episode to, from the shows you choose, as it is transcribed and again once its sponsors, people and topics are known. Episodes arrive in signed batches, in order, one batch at a time, and nothing is skipped: a batch your server does not accept is retried until it is, and nothing after it is sent meanwhile. It is how to keep your own copy of new episodes without polling.

A firehose sends what Podzone knows about each episode, not its transcript. Each event links to the transcript, which you fetch with your API key when you want it.

## Adding a firehose

A team can have one firehose, on the plans that include it ([pricing](https://podzone.fm/pricing)). An account admin adds it on the app's Firehose page, or an integration adds it with [`POST /api/v1/firehoses`](https://api.podzone.fm/api/v1/docs#tag/firehose/operation/create_firehose):

```bash
curl https://api.podzone.fm/api/v1/firehoses \
  -H "Authorization: Bearer $PODZONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/podzone/firehose",
    "podcast_ids": ["0190b6a2-...", "0190b6a3-..."],
    "types": ["episode.transcribed", "episode.enriched"]
  }'
```

- **`podcast_ids`** are the shows to send, by the `id` [podcast search](https://api.podzone.fm/api/v1/docs#tag/podcasts/operation/search_podcasts) gives each. Your plan sets how many shows your account's firehoses may name between them, each show counted once however many teams name it. Past that, the request is refused with `403 plan_limit_reached`.
- **`category_slugs`**, or no shows at all for every show, are on Business; on Pro they are refused with `403 upgrade_required`.
- **`types`** narrows it to `episode.transcribed` or `episode.enriched`. Left out, it sends both.

The URL must be `https`, on a host that resolves to a public address. The response carries the firehose's signing `secret`, which starts `whsec_`. It is returned only this once: store it with your other secrets, or [rotate it](https://api.podzone.fm/api/v1/docs#tag/firehose/operation/rotate_firehose_secret) for a new one. A new firehose starts with the next new episode; [replay](#replays-and-gaps) to receive the last few days as well.

## What is sent

Each POST is one batch:

```json
{
  "type": "firehose.batch",
  "timestamp": "2026-11-13T09:40:12.123Z",
  "test": false,
  "data": {
    "firehose_id": "...",
    "has_more": false,
    "gap": null,
    "events": [
      {
        "id": "...",
        "type": "episode.transcribed",
        "timestamp": "2026-11-13T09:39:58.000Z",
        "data": { "episode": { "id": "...", "title": "...", "...": "..." }, "transcript_url": "..." }
      }
    ]
  }
}
```

The [event's entry in the API reference](https://api.podzone.fm/api/v1/docs#tag/webhook-events/operation/firehose_batch) lists every field.

- **`episode.transcribed`**: a new episode was transcribed. `data.episode` is exactly what [`GET /api/v1/episodes/{episode_id}`](https://api.podzone.fm/api/v1/docs#tag/episodes/operation/get_episode) returns, show notes included.
- **`episode.enriched`**: usually minutes later, the same episode with what it is about: `sponsors`, `people` and `topics`, as the episode's own routes list them.

Each episode's events are sent once each, oldest first, for episodes published in the last seven days. Back-catalogue episodes are not sent.

**`transcript_url`** is the episode's [transcript download](https://api.podzone.fm/api/v1/docs#tag/episodes/operation/download_episode_transcript): fetch it with your API key, adding `?format=txt`, `srt` or `vtt` for those instead of JSON. Each fetch is one of your plan's transcript downloads and one API request, so fetch the transcripts you need rather than every one. Batches themselves count against nothing.

**An event can arrive twice**, after a replay or a retry of a batch your server did accept. Each event's `id` stays the same, so drop the ones you have already stored.

## Verifying a batch

Batches are signed exactly as webhook deliveries are, following [Standard Webhooks](https://www.standardwebhooks.com), with the firehose's own secret: [the webhooks guide](https://podzone.fm/docs/webhooks#verifying-a-delivery) shows how to check the signature, with the libraries or by hand. `webhook-id` is the batch's id, the same on every retry of that batch.

## Responding and retries

Acknowledge first and do the work afterwards: store the body, reply, then process it.

- **Up to 100 events a batch,** and at most 512 KB: a batch is cut before the event that would take it past that, and the rest follow at once.
- **Reply within 5 seconds** with any `2xx`. Any other status, a timeout or a redirect is a failed attempt.
- **A failed batch is retried 7 more times**, after 5 s, 25 s, 2 min, 10 min, 52 min, 4.3 h and 21.7 h: 8 attempts over about 27 hours.
- **Test events are limited to 50 an hour** per team.

**Nothing after a batch is sent until it is accepted,** so a batch your server cannot take holds the firehose where it is. When `has_more` is true, the next batch follows as soon as this one is accepted, until the firehose has caught up; after that, batches come about once a minute while new episodes arrive.

## When a firehose is switched off

When a batch has failed every attempt, Podzone switches the firehose off and emails the account's admins. Nothing is skipped: the firehose stays at the batch that failed. Switch it back on from the app or by [sending `is_active: true`](https://api.podzone.fm/api/v1/docs#tag/firehose/operation/update_firehose) once your server is answering, and it carries on from there.

[`GET /api/v1/firehoses/{firehose_id}`](https://api.podzone.fm/api/v1/docs#tag/firehose/operation/get_firehose) shows `is_active` and, for one Podzone switched off, `disabled_reason`: `failing` after failed batches, or `plan` when the account's plan no longer includes it or its shows. To try a fixed server before the next attempt is due, [retry now](https://api.podzone.fm/api/v1/docs#tag/firehose/operation/retry_firehose).

## Replays and gaps

Events are kept for seven days. [Replaying](https://api.podzone.fm/api/v1/docs#tag/firehose/operation/replay_firehose) moves the firehose back to a time within them and sends everything from there again, in order, then carries on with new episodes: to fill a new receiver, or to recover from a bug in yours.

A firehose that is off for longer than seven days cannot be sent what it missed. Switched back on, it resumes from the oldest event kept, and its next batches carry a `gap`: `from` and `until`, the stretch it can never be sent. Fill it from the API, by [listing each show's episodes](https://api.podzone.fm/api/v1/docs#tag/podcasts/operation/list_podcast_episodes).

## Test batches

The Firehose page in the app, or [`POST /api/v1/firehoses/{firehose_id}/test`](https://api.podzone.fm/api/v1/docs#tag/firehose/operation/test_firehose), sends a batch of two sample events with `"test": true`, signed with the firehose's secret. Pass a `url` to send it somewhere else, such as a tunnel to your machine. It is sent once, never retried, works while the firehose is off, and never moves it on. Ignore `"test": true` batches in production.

## Troubleshooting

Every batch and its outcome is in the firehose's [batch log](https://api.podzone.fm/api/v1/docs#tag/firehose/operation/list_firehose_batches), also on the app's Firehose page: its status, how many events it carried, the HTTP status your server answered with, and `last_error` when there was no answer.

- **Nothing arrives.** Check that the firehose `is_active`, and that its shows have published new episodes. A new firehose starts with the next one.
- **The same batch keeps arriving.** Your server is not answering it with a `2xx` in time. Reply before processing it; a slow handler fails even when it eventually succeeds.
- **A batch was `cancelled`.** The firehose was changed, replayed or switched off while the batch was out; its events are sent again in a new batch.
- **The signature never matches.** See [the webhooks guide's troubleshooting](https://podzone.fm/docs/webhooks#troubleshooting): the same causes apply.
