Firehose

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

View as Markdown

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). An account admin adds it on the app's Firehose page, or an integration adds it with POST /api/v1/firehoses:

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 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 for a new one. A new firehose starts with the next new episode; replay to receive the last few days as well.

What is sent #

Each POST is one batch:

{
  "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 lists every field.

  • episode.transcribed: a new episode was transcribed. data.episode is exactly what GET /api/v1/episodes/{episode_id} 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: 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, with the firehose's own secret: the webhooks guide 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 once your server is answering, and it carries on from there.

GET /api/v1/firehoses/{firehose_id} 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.

Replays and gaps #

Events are kept for seven days. Replaying 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.

Test batches #

The Firehose page in the app, or POST /api/v1/firehoses/{firehose_id}/test, 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, 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: the same causes apply.