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 JWP video process.
If you are not a developer or prefer a simpler implementation, you can use Zapier to create Zaps to manage your notifications.
Prerequisites
| Item | Description |
|---|---|
| Secret | Unique user API credential Follow these steps to obtain the secret:
|
| Property ID | Unique identifier of the JWP property Follow this step to obtain a property ID:
|
Available webhook events
JWP's webhooks support the following notifications.
When creating webhooks in your account, you will only see events that correspond to your enabled account features and entitlements.
Conversions
| Event | Description |
|---|---|
| Conversions Complete | Notification sent when both the thumbnail is ready and all initial video renditions have been processed
This event is only fired for the first media upload, and not when the media's original is replaced through a reupload. Event Example |
Live channel
| Event | Description |
|---|---|
| Live channel Is active | Notification sent when a Live Channel enters an active state
Event Example |
| Live channel Is idle | Notification sent when a Live Channel enters an idle state
Event Example |
| Live channel Created | Notification sent when a Live Channel is created
Event Example |
Media
| Event | Description |
|---|---|
| Media Available | Notification sent when media is first publishable and indexed
At this point, the thumbnail is ready, but not all video renditions, such as those with higher resolutions, may have finished processing. If your media has a publish start date in the future, no Media Available notification will be sent. Event Example |
| Media Created | Notification sent when media has been first uploaded
Event Example |
| Media Deleted | Notification sent when media has been deleted
Event Example |
| Media Reuploaded | Notification sent when a media has been reuploaded
The Media Reuploaded notification is the point at which the reupload has been initiated, not the time at which the reupload has been fully processed. You will receive Conversion Complete and Media Available notifications when conversions have been indexed and the media is first publishable. Event Example |
| Media Updated | Notification sent when a media is updated
A Media Updated notification is sent when any fields in the metadata or relationships objects of a media item are updated using the media patch endpoint directly or where used in the JWP dashboard.
Event Example |
Stream
| Event | Description |
|---|---|
| Stream Created | Notification sent when the Broadcast Live stream has been successfully created
Event Example |
| Stream Deleted | Notification sent when the the Broadcast Live stream has been deleted
Event Example |
| Stream Go live | Notification sent when the Broadcast Live stream has become available
Event Example |
| Stream Transitioned | Notification sent when the Broadcast Live stream has transitioned to a new state
Event Example |
| Stream Updated | Notification sent when the properties of the Broadcast Live stream have changed
Event Example |
Thumbnail
| Event | Description |
|---|---|
| Thumbnail Created | Notification sent when a thumbnail is created
Event Example |
| Thumbnail Deleted | Notification sent when a thumbnail is deleted
Event Example |
Track
| Event | Description |
|---|---|
| Track Created | Notification sent when a track is created
Event Example |
| Track Deleted | Notification sent when a track is deleted
Event Example |
Create a webhook
In your platform and language of choice, follow the steps in the recipe below to create a webhook.
Use case
Problem: A publisher wants to automate the publishing workflow for two properties (with keys 1A23bCD4 and 2B34cDE5). Without polling JWP's API, the publisher wants to receive a notification whenever newly uploaded videos are ready to be published for either property.
Solution: The publisher must create a webhook that subscribes to the Media Available (media_available) notification event. By including multiple site_ids, the webhook can fire for both properties in the account.
The publisher makes the following query.
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", "2B34cDE5"]
}
}'
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", "2B34cDE5"],
"webhook_url": "https://my-endpoint.com"
},
"schema": null,
"secret": "efZQiWvaaoqx1Hpgi-hhLGInZUhWa1UyWjVaVk5ZVldoR2FVZERja3BoV0hWNE4xTjYn",
"type": "webhook"
}
Verify the authenticity of a webhook
JWP gives you the ability to verify the authenticity of a webhook. To verify that a webhook originated from JWP, JWP'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.
JWP'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.