Using the Firehose Webhook
Think of the Firehose Webhook as a direct pipeline sending new podcast data straight to your systems. It'sa near-realtime push API that sends newly transcribed episodes the moment our system makes them available.
Podscan Firehose API is a powerful tool for developers who want to access and integrate Podscan's large database of podcast data into their own applications or services. The API provides real-time access to the continually updated stream of podcast episodes and metadata, allowing developers to keep their applications up-to-date with the latest podcast content.
It's designed to be easy to use and flexible, accommodating a wide range of use cases and applications.
Whether you're building a podcast discovery app, a podcast analytics service, or any other podcast-related application, the Podscan Firehose API can provide the data you need.
Imagine a news wire service, but for podcasts. The Firehose:
- Sends you episodes the moment they're published
- Includes full transcripts
- Delivers detailed information about each show
- Works 24/7 without you checking anything
The Podscan Firehose API operates as a webhook-based push API. This means that it allows every team on Podscan to route data from every new episode to their servers, usually within minutes after it's published.
This system ensures that the data you receive is always the most current, allowing your application or service to stay up-to-date with the latest podcast episodes and information.
You might need the Firehose if:
- You're monitoring thousands of mentions
- Your team needs data in real-time
- You're connecting Podscan to other tools
- You're building custom reports or dashboards
If you're just getting started, regular email alerts might be enough.
[Screenshot: Comparison of email alerts vs Firehose]
The basic setup is straightforward:
Open your Team Settings
Go to your API & Firehose settings
Turn on "Enable the Podscan Firehose webhook"
Add your webhook URL (where you want data sent). Ensure that this endpoint can be called from the Podscan servers.
Choose if you want to restrict it to certain categories or podcasts. This will strongly affect the number of webhooks you'll receive per day.
Each update includes:
- The podcast episode details
- Full transcript text
- Show information and metadata
Here's an example payload:
By default, the JSON body is sent as a gzipped JSON string, as indicated by the presence of the Content-Encoding: gzip header. This significantly reduces the size of the payload sent to your server, particularly for long transcripts.
This section provides detailed descriptions of the fields returned in our API response for podcast and episode information. The format delivered by the API is JSON.
podcast_name : (string) The name of the podcast series.
podcast_url : (string) The URL to the main page of the podcast
podcast_id : (string) A unique identifier for the podcast series.
podcast_itunes_rating_count : (string) A bracket value for how many iTunes Apple Podcast reviews this podcast has. One of these values: “Unknown”, "0-10", "10-100", "100-250", "250-1k", "1k-5k", "5k-20k", "20k-75k", "75k-150k", "150k-500k", "500k-1m", "1m-5m", "5m+”
episode_id : (string) A unique identifier for the specific episode.
episode_title : (string)The title of the specific podcast episode.
episode_description : (string) A brief description of the episode's content.
episode_url : (string) The URL to access the specific podcast episode on the podcast website.
episode_transcript : (string) The full transcript of the episode, including timestamps and dialogue.
episode_posted_at : (string) The date and time when the episode was posted, formatted as "YYYY-MM-DD HH:MM:SS".
episode_posted_at_atom : (string) The date and time when the episode was posted in the ISO8601 ( 2012-01-18T11:45:00+01:00 ) format.
Any field can return a null value if no proper value exists.
These fields provide comprehensive information about both the podcast series and individual episodes, including how to access them and details about their content. New fields will be added to the firehose data object over time. When you implement a response parser, keep that in mind and allow for parsing JSON with additional fields.
The Firehose can send a lot of data. Control it by:
- Limiting to specific podcast categories
- Filtering for certain shows only
- Setting up rules for what you receive on the receiving end
Depending on how many podcasts and categories you select, your daily expected number of webhooks sent will be shown, so you can calculate eventual resource constraints before we start sending you data.
You may select any number of podcasts and categories for your Firehose.
Teams use the Firehose to:
- Implement their own checking and analysis logic on top of the raw data
- Provide new podcast episodes to their customers and users in real-time
Start with a test endpoint
Monitor your first day of data
Add filters if needed
Set up error alerts
Remember: The Firehose sends A LOT of data. Make sure your system can handle it.
Our team can help you:
- Set up your first connection
- Understand the data format
- Solve technical problems
- Plan your integration
Just reach out to our support team.
Podscan Firehose API is a powerful tool for developers who want to access and integrate Podscan's large database of podcast data into their own applications or services. The API provides real-time access to the continually updated stream of podcast episodes and metadata, allowing developers to keep their applications up-to-date with the latest podcast content.
It's designed to be easy to use and flexible, accommodating a wide range of use cases and applications.
Whether you're building a podcast discovery app, a podcast analytics service, or any other podcast-related application, the Podscan Firehose API can provide the data you need.
What Is The Firehose?
Imagine a news wire service, but for podcasts. The Firehose:
- Sends you episodes the moment they're published
- Includes full transcripts
- Delivers detailed information about each show
- Works 24/7 without you checking anything
The Podscan Firehose API operates as a webhook-based push API. This means that it allows every team on Podscan to route data from every new episode to their servers, usually within minutes after it's published.
This system ensures that the data you receive is always the most current, allowing your application or service to stay up-to-date with the latest podcast episodes and information.
When To Use It
You might need the Firehose if:
- You're monitoring thousands of mentions
- Your team needs data in real-time
- You're connecting Podscan to other tools
- You're building custom reports or dashboards
If you're just getting started, regular email alerts might be enough.
[Screenshot: Comparison of email alerts vs Firehose]
Setting It Up
The basic setup is straightforward:
Open your Team Settings
Go to your API & Firehose settings
Turn on "Enable the Podscan Firehose webhook"
Add your webhook URL (where you want data sent). Ensure that this endpoint can be called from the Podscan servers.
Choose if you want to restrict it to certain categories or podcasts. This will strongly affect the number of webhooks you'll receive per day.
What You'll Receive
Each update includes:
- The podcast episode details
- Full transcript text
- Show information and metadata
Here's an example payload:
{
"podcast_name": "Dana Tyson In The Morning on Sunny 99.1",
"podcast_url": "https:\/\/www.iheart.com\/podcast\/527-sunny-991-mornings-28256526\/",
"podcast_id": "pd_6go3jm6knxl92la7",
"podcast_itunes_rating_count": "0-10",
"episode_title": "TX in zone of uncertainty for Rafael, Houston Humane Society brings dogs to polls, What is your dating deal-breaker?",
"episode_description": "Dana In The Morning Highlights 11\/6TX is keeping tabs on Tropical Storm Rafael as it looks to make landfall next Wednesday...",
"episode_url": "https:\/\/www.spreaker.com\/episode\/tx-in-zone-of-uncertainty-for-rafael-houston-humane-society-brings-dogs-to-polls-what-is-your-dating-deal-breaker--62640633",
"episode_transcript": "[00:00:01.710 --> 00:00:12.150] SUNNY 99.1, Houston's best variety, the 80s, 90s, and today, Dana In The Morning and producer Anthony and the three things you ...",
"episode_posted_at": "2024-11-06 15:24:03",
"episode_posted_at_atom": "2024-11-06T15:24:03+00:00",
"episode_id": "ep_eb98jy2oaze7rmga"
}By default, the JSON body is sent as a gzipped JSON string, as indicated by the presence of the Content-Encoding: gzip header. This significantly reduces the size of the payload sent to your server, particularly for long transcripts.
This section provides detailed descriptions of the fields returned in our API response for podcast and episode information. The format delivered by the API is JSON.
Fields
podcast_name : (string) The name of the podcast series.
podcast_url : (string) The URL to the main page of the podcast
podcast_id : (string) A unique identifier for the podcast series.
podcast_itunes_rating_count : (string) A bracket value for how many iTunes Apple Podcast reviews this podcast has. One of these values: “Unknown”, "0-10", "10-100", "100-250", "250-1k", "1k-5k", "5k-20k", "20k-75k", "75k-150k", "150k-500k", "500k-1m", "1m-5m", "5m+”
episode_id : (string) A unique identifier for the specific episode.
episode_title : (string)The title of the specific podcast episode.
episode_description : (string) A brief description of the episode's content.
episode_url : (string) The URL to access the specific podcast episode on the podcast website.
episode_transcript : (string) The full transcript of the episode, including timestamps and dialogue.
episode_posted_at : (string) The date and time when the episode was posted, formatted as "YYYY-MM-DD HH:MM:SS".
episode_posted_at_atom : (string) The date and time when the episode was posted in the ISO8601 ( 2012-01-18T11:45:00+01:00 ) format.
Any field can return a null value if no proper value exists.
These fields provide comprehensive information about both the podcast series and individual episodes, including how to access them and details about their content. New fields will be added to the firehose data object over time. When you implement a response parser, keep that in mind and allow for parsing JSON with additional fields.
Making It More Manageable
The Firehose can send a lot of data. Control it by:
- Limiting to specific podcast categories
- Filtering for certain shows only
- Setting up rules for what you receive on the receiving end
Depending on how many podcasts and categories you select, your daily expected number of webhooks sent will be shown, so you can calculate eventual resource constraints before we start sending you data.
You may select any number of podcasts and categories for your Firehose.
Common Uses
Teams use the Firehose to:
- Implement their own checking and analysis logic on top of the raw data
- Provide new podcast episodes to their customers and users in real-time
Getting Started Tips
Start with a test endpoint
Monitor your first day of data
Add filters if needed
Set up error alerts
Remember: The Firehose sends A LOT of data. Make sure your system can handle it.
Need Help?
Our team can help you:
- Set up your first connection
- Understand the data format
- Solve technical problems
- Plan your integration
Just reach out to our support team.
Updated on: 06/11/2024
Thank you!