Webhooks

Example use-cases:

• Do you care about SEO? Get a webhook notification immediately whenever your website is mentioned on a new episode.

• Do you want industry specific leads or insights? Get a webhook notification immediately when a person or a brand has been mentioned on a new episode.

• Do you want to push notify your users whenever a new episode is released? Get a webhook notification immediately when a new episode is released. On your server, you match which users want a push notification and send one to them.

Setting Up a Webhook

• Open up the Taddy Dashboard, you will see a “Setup a New Webhook” button.

• You will have to enter in:
1. The endpoint url where you want to receive the notifications (usually on your own server)
2. Pick which webhook events you would like to receive.

• You must be on a paid plan to add a webhook to your account.

• Webhook notifications do not count against your monthly API limits 🥳.

• The endpoint url you enter needs to be one publicly accessible over the internet. (For example, 127.0.0.1 and localhost URLs will not work, since Taddy servers will not be able to contact your local computer). If you’d like to test receiving these notifications locally on your computer, Ngrok provides a useful & free way to do so. It provides you a public url that is mapped to your localhost.

• Your endpoint url needs to be a POST endpoint

• In the Webhooks section, one of the fields given to you is the Webhook Secret. This is an optional security feature. We add this secret as the header X-TADDY-WEBHOOK-SECRET to all webhook notifications sent to this webhook. Because your endpoint url is publicly accessible and if you dont share this secret with anyone else, you can be confident that any data you receive on your endpoint is from us and can be trusted.

• Listen Up is a very simple app that receives and displays webhook events. It may be useful to you as a very easy way to see what kind of events are going to be received by your webhook endpoint.

• There is an example project which allows you to mock webhook events. It's a great way to test receiving webhook events before receiving the live events from Taddy’s API.

Webhook Events

PodcastSeries

PodcastEpisode

iTunesInfo

What does a webhook event look like?

Examples:

// EXAMPLE WEBHOOK EVENT for a PodcastSeries event
{
  uuid: 'cb8d858a-3ef4-4645-8942-67e55c0927f2',
  taddyType: 'podcastseries',
  action: 'updated',
  timestamp: 1673984316,
  data: {
    uuid: 'cb8d858a-3ef4-4645-8942-67e55c0927f2',
    hash: 'b8f97d07ce3a9916aeba1feda9db610b58aee8d62a2dfa0495a0b1893e857d91',
    name: 'The Daily',
    description: 'This is what the news should sound like. The biggest stories of our time, told by the best journalists in the world. Hosted by Michael Barbaro and Sabrina Tavernise. Twenty minutes a day, five days a week, ready by 6 a.m.',
    imageUrl: 'https://image.simplecastcdn.com/images/03d8b493-87fc-4bd1-931f-8a8e9b945d8a/2cce5659-f647-4366-b318-46e4b67afcfa/3000x3000/c81936f538106550b804e7e4fe2c236319bab7fba37941a6e8f7e5c3d3048b88fc5b2182fb790f7d446bdc820406456c94287f245db89d8656c105d5511ec3de.jpeg?aid=rss_feed',
    datePublished: 1484687987,
    language: 'ENGLISH',
    seriesType: 'EPISODIC',
    contentType: 'AUDIO',
    isExplicitContent: false,
    copyright: '© 2020-2021 THE NEW YORK TIMES COMPANY; The New York Times encourages the use of RSS feeds for personal use in a news reader or as part of a non-commercial blog, subject to your agreement to our Terms of Service.',
    websiteUrl: 'https://www.nytimes.com/the-daily',
    rssUrl: 'https://feeds.simplecast.com/54nAGcIl',
    rssOwnerName: 'The New York Times',
    rssOwnerPublicEmail: '[email protected]',
    authorName: 'The New York Times',
    isCompleted: false,
    isBlocked: null,
    itunesId: 1200361736,
    genres: [ 'PODCASTSERIES_NEWS_DAILY_NEWS', 'PODCASTSERIES_NEWS' ],
    childrenHash: '95ef1fee188406c415e32915f85855eab3cf49e0f9052785e42ef368792333db',
    popularityRank: 'TOP_200',
    itunesInfo: {
      uuid: 'cb8d858a-3ef4-4645-8942-67e55c0927f2',
      publisherId: 121664449,
      publisherName: 'The New York Times',
      baseArtworkUrl: 'https://is1-ssl.mzstatic.com/image/thumb/Podcasts115/v4/1c/ac/04/1cac0421-4483-ff09-4f80-19710d9feda4/mza_12421371692158516891.jpeg/',
      baseArtworkUrlOf: 'https://is1-ssl.mzstatic.com/image/thumb/Podcasts115/v4/1c/ac/04/1cac0421-4483-ff09-4f80-19710d9feda4/mza_12421371692158516891.jpeg/640x640bb.png'
    }
  }
}

// EXAMPLE WEBHOOK EVENT for a PodcastEpisode event
{
  uuid: 'a2b41ecd-565c-4f29-8cf9-ac737bcc8d99',
  taddyType: 'podcastepisode',
  action: 'updated',
  timestamp: 1673984261,
  data: {
    uuid: 'a2b41ecd-565c-4f29-8cf9-ac737bcc8d99',
    hash: '8130da98420b6ea1bcafd9a7e411625bf0437e93cd2e44b0a2291430e7cd940c',
    name: 'Consider the Burying Beetle. (Or Else.)',
    description: '<p>The current level of biodiversity loss is extraordinary in human history: The global rate of species extinction is at least tens to hundreds of times higher than the average over the past 10 million years. </p><p>At the end of 2022, countries around the world came together in Montreal for an agreement akin to the Paris climate accord to tackle the biodiversity crisis. Here’s more on the effort and how it seeks to confront the problem.</p><p>Guest: <a href="https://www.nytimes.com/by/catrin-einhorn">Catrin Einhorn</a>, who reports on biodiversity and climate for The New York Times.</p><p>Background reading: </p><ul><li>Last year, roughly 190 nations, aiming to halt a dangerous decline in biodiversity,<a href="https://www.nytimes.com/2022/12/19/climate/biodiversity-cop15-montreal-30x30.html"> agreed to preserve 30 percent of the planet’s land and seas</a>. </li></ul><p>For more information on today’s episode, visit <a href="http://nytimes.com/thedaily?smid=pc-thedaily">nytimes.com/thedaily</a>. Transcripts of each episode will be made available by the next workday. </p>\n',
    imageUrl: null,
    datePublished: 1673001900,
    guid: '848d3475-dc4d-4c53-b97c-e69f05bad846',
    subtitle: 'The current level of biodiversity loss is extraordinary in human history: The global rate of species extinction is at least tens to hundreds of times higher than the average over the past 10 million years. \n' +
      '\n' +
      'At the end of 2022, countries around the world came together in Montreal for an agreement akin to the Paris climate accord to tackle the biodiversity crisis. Here’s more on the effort and how it seeks to confront the problem.\n' +
      '\n' +
      'Guest: Catrin Einhorn, who reports on biodiversity and climate for The New York Times.',
    audioUrl: 'https://dts.podtrac.com/redirect.mp3/chrt.fm/track/8DB4DB/pdst.fm/e/nyt.simplecastaudio.com/03d8b493-87fc-4bd1-931f-8a8e9b945d8a/episodes/b8f7e904-bf5d-4c60-b3d7-de67dfc271fc/audio/128/default.mp3?aid=rss_feed&awCollectionId=03d8b493-87fc-4bd1-931f-8a8e9b945d8a&awEpisodeId=b8f7e904-bf5d-4c60-b3d7-de67dfc271fc&feed=54nAGcIl',
    videoUrl: null,
    fileLength: 24695702,
    fileType: 'audio/mpeg',
    duration: 1543,
    episodeType: 'FULL',
    seasonNumber: null,
    episodeNumber: null,
    websiteUrl: 'https://www.nytimes.com/the-daily',
    isExplicitContent: false,
    isRemoved: null,
    podcastSeries: {
      uuid: 'cb8d858a-3ef4-4645-8942-67e55c0927f2',
      name: 'The Daily',
      rssUrl: 'https://feeds.simplecast.com/54nAGcIl',
      itunesId: 1200361736
    }
  }
}

// EXAMPLE WEBHOOK EVENT for a iTunesInfo event
{
  uuid: 'cb8d858a-3ef4-4645-8942-67e55c0927f2',
  taddyType: 'itunesinfo',
  action: 'updated',
  timestamp: 1673984345,
  data: {
    uuid: 'cb8d858a-3ef4-4645-8942-67e55c0927f2',
    hash: '2c022ad3c4482664cdecbcb05e87313e917aff2b697f1f674b69bb6514f55ed6',
    subtitle: null,
    summary: 'This is what the news should sound like. The biggest stories of our time, told by the best journalists in the world. Hosted by Michael Barbaro and Sabrina Tavernise. Twenty minutes a day, five days a week, ready by 6 a.m.',
    baseArtworkUrl: 'https://is1-ssl.mzstatic.com/image/thumb/Podcasts115/v4/1c/ac/04/1cac0421-4483-ff09-4f80-19710d9feda4/mza_12421371692158516891.jpeg/',
    publisherId: 121664449,
    publisherName: 'The New York Times',
    country: 'UNITED_STATES_OF_AMERICA',
    podcastSeries: {
      uuid: 'cb8d858a-3ef4-4645-8942-67e55c0927f2',
      name: 'The Daily',
      rssUrl: 'https://feeds.simplecast.com/54nAGcIl',
      itunesId: 1200361736
    }
  }
}

Recommended Architecture for Webhooks

• Taddy API is continuously checking 4 million podcast feeds for new and updated podcast data. Whenever we update our database with new data, we also send it to you via your Webhook endpoint (1)

• We recommend using a lambda function (or equivalent) for your Webhook endpoint. The function receives new podcast data from Taddy API and adds it to a queue to be processed at a later time. (2)

• We recommend having a worker (or workers) process messages in your queue and add this data into your database. Set up a Dead-letter Queue for failed message processing, which can be re-processed at a later time (3)