Webhooks

If you're technical and wish to receive notifications for events related to your podcast, you can configure webhooks. If you're building a third party application, you can use webhooks to receive updates about your users' podcasts hosted on Pinecast.

Webhooks are available as part of the Notifications feature that's available with our Crew Add-on.

Webhook format

Pinecast will POST a JSON blob to the URL provided in the podcast settings dashboard. Webhooks have a five second timeout (from the time of connection until a response is received). Failed webhooks are not retried.

Body

The following fields are available on the JSON body (where foo.bar represents the field bar nested within an object on the field foo):

• summary: A text summary of the notification. E.g., "Tip of $5.00 from test-tipper@pinecast.com"

• link: The URL associated with the webhook. This generally links to the Pinecast podcast or episode dashboard associated with the event.

• podcast: A hash containing information about the podcast associated with the webhook.

• podcast.name: The name of the podcast.

• podcast.slug: The slug of the podcast. This can be used to format URLs.

• podcast.url: The URL of the podcast dashboard.

• podcast.feed_url: The URL of the podcast's RSS feed.

• type: The name of the webhook's trigger. This is one of tip, feedback, first_listen, listen_threshold, published, or growth_milestone.

If type is tip, the following fields are available:

• tipper: Email address of the listener that left a tip.

• amount: Value of the tip in cents (USD).

If type is feedback, the following fields are available:

• episode: A hash containing information about the associated episode, if the feedback is about an episode.

• content: The contents of the feedback.

If type is first_listen or published, the following fields are available:

• episode: A hash containing information about the episode that received its first listen.

If type is listen_threshold, the following fields are available:

• episode: A hash containing information about the episode that crossed the listen threshold.

• threshold: The integer threshold that was crossed.

If type is growth_milestone, the following fields are available:

• listens: The number of listens that the podcast has received so far.

• milestone: The number of listens that the podcast exceeded in order to cross the threshold.

Episode hashes contain the following fields:

• id: The UUID associated with the episode.

• title: The episode title.

• url: The URL of the episode in the podcast dashboard.

• listen_url: A URL that redirects to the episode audio file. Accessing this URL will count a listen with the source "direct".

• player_url: The URL of the episode's embeddable player. In order to use this, you must manually format the <iframe> tag for the player's HTML source. Be sure to add a theme query string parameter and height.

• publish: An ISO 8601-formatted date denoting when the episode was published.