Learn about webhooks

Receive notifications about media assets without polling the JW Platform Management API.

Webhooks allow you to automate your workflow by notifying you when specific events occur in the JW Player video process.

📘

GOALS

After completing this article, you should be able to answer the following questions:
  • How do I create a new webhook?
  • How do I verify the authenticity of a webhook?
  • Where can I find information about the available API calls for webhooks


If you are not a developer or prefer a simpler implementation, you can use Zapier to create Zaps to manage your notifications.



Requirement

Before you begin to use JW Player's webhooks, you need your secret.

ItemDescription
SecretUnique user API credential

1. From your API Credentials page, scroll down to the V2 API Credentials section.

2. Click Show Credentials in the row of the relevant API key name.

NOTE: If no API key names exist, type a new API key name, select a permission level, and click Add New API Key. Your account must have the Admin permission to create a new API key.

3. Copy the Secret.


Create a webhook

JW Player's webhooks support the following notifications.

NotificationDescription
Channel ActiveNotification sent when a Live Channel enters an active state
Channel CreatedNotification sent when a Live Channel is created
Channel IdleNotification sent when a Live Channel enters an idle state
Conversions CompleteNotification sent when all conversions have been transcoded & indexed
Media AvailableNotification sent when media is first publishable & indexed

Both the thumbnail is ready and the initial video renditions have been transcoded. If your media has publish start date in the future, no Media Available notification will be sent.
Media DeletedNotification sent when media has been deleted
Media ReuploadedNotification sent when a media has been reuploaded

The Media Reuploaded notification is not the time at which the reupload has been fully processed, but the point at which the reupload has been initiated. You will receive Conversion Complete and Media Available notifications when conversions have been indexed and the media is first publishable.
Media UpdatedNotification sent when a media is updated

Webhooks are enabled at the property level. So, if you have multiple properties under a single account, you will need to create webhooks for each property.


In your platform or language of choice, use the following steps to create a webhook:

  1. Create a POST api.jwplatform.com/v2/webhooks call.
  2. Add your secret to the header of your POST call to authenticate your request. For example, in the use case below: 'Authorization: 123Four56==7123Four56==7'
  3. Create a request body. The request body must include a metadata object that defines the appropriate webhook properties.
  4. Append the query body to your POST request.
  5. Execute the API POST request.

👍

USE CASE

A publisher wants to automate the publishing workflow for a property whose key is 1A23bCD4. Without needing to poll JW Player's API, the publisher wants to know when newly uploaded videos are ready to be published to its site.


SOLUTION: The publisher must create a webhook for the property (1A23bCD4) that subscribes to the Media Available (media_available) notification. As noted in the table at the beginning of the section, the Media Available notification event indicates when media has been indexed and can be shared.

curl -X POST https://api.jwplayer.com/v2/webhooks \
 -H 'Authorization: 123Four56==7123Four56==7' \
 -H 'Content-Type: application/json' \
 -d '{"metadata": {"name" : "Media Available Webhook", "description": "Webhook to notify me when media is ready to be published", "webhook_url": "https://my-endpoint.com", "events": ["media_available"], "site_ids": ["1A23bCD4"]}}'

If the API call is successful, the publisher receives the following response.

{
    "created": "2019-09-05T11:54:37.182547+00:00",
    "id": "c0Y6ebVU",
    "last_modified": "2019-09-05T11:54:37.182547+00:00",
    "metadata": {
        "description": "Webhook to notify me when media is ready to be published",
        "events": [
            "media_available"
        ],
        "name": "Media Available Webhook",
        "site_ids": ["1A23bCD4"],
        "webhook_url": "https://my-endpoint.com"
    },
    "schema": null,
    "secret": "efZQiWvaaoqx1Hpgi-hhLGInZUhWa1UyWjVaVk5ZVldoR2FVZERja3BoV0hWNE4xTjYn",
    "type": "webhook"
}


Verify the authenticity of a webhook

JW Player gives you the ability to verify the authenticity of a webhook. To verify that a webhook originated from JW Player, JW Player's webhooks use JWT encryption.

When a webhook is created, the JSON response contains a secret property. The value of the secret is the shared key used for decryption. Be sure to securely store the value of the secret. This secret is returned only in the response to the POST api.jwplatform.com/v2/webhooks call.

Incoming webhooks include a header Authorization whose value is Bearer {Token}. The token is generated by hashing the webhook payload with the shared secret.

To verify the authenticity of a webhook, use the JWT decode method. The {Token} and secret should be used as arguments in the decode method. The value returned from this method should equal the body sent in the request.


🚧

IMPORTANT

JW Player's webhooks do not support a rotating webhook secret. In order to generate a new webhook secret, you must first delete the existing webhook and then, create a new webhook.


The following code example shows how this workflow might look in Python.

"""
Sample code showing how to decode the JWT token to verify authenticity of sender
"""

import json
import jwt


def parse_token_from_request(request):
  """
  Extracts JWT token from Authorization header

  Args:
    request: Incoming HTTP Request
    
  Returns:
    bytes: JWT token
  """
  # The header will be in the form of "Authorization: Bearer {Token}"
  return request.headers["Authorization"].split(" ")[1]


def verify_authenticity(jwt_token, webhook_secret, webhook_payload):
  """
  Uses the JWT Token and Request body to verify 
    
  Args:
    jwt_token (bytes): token
    webhook_secret (str): shared secret returned on POST /v2/webhooks
    webhook_payload (json): Incoming Webhook notification JSON body
  """
  jwt_payload = jwt.decode(jwt_token, webhook_secret, algorithms=["HS256"])
  return jwt_payload == webhook_payload


def webhook_handler(request):
  """
  Route handler for the endpoint handling incoming webhooks

  Args:
    request: Incoming request
  """
  jwt_token = parse_token_from_request(request)
  # This assumes a Flask implementation, but parse JSON body
  webhook_payload = json.loads(request.data)

  # This represents the shared secret returned on POST /v2/webhooks
  # This should be stored securely.
  shared_secret = "secret!"

  is_jw_webhook = verify_authenticity(jwt_token, shared_secret, webhook_payload)

  if is_jw_webhook:
    # Congrats it is a valid JW webhook!
    process_webhook(webhook_payload)
  else:
    # Not a JW webhook!
    return


Understand available webhooks API routes

In addition to creating webhooks, you can list, return, update, and delete webhooks.

Click the badges below to read the API explanation of each route.

   List all webhooks on the account
   Retrieve a webhook resource by ID
   Delete a webhook resource
   Update a webhook resource



Did this page help you?