A webhook is a real-time system that delivers data to other applications as it happens. This means that you get data immediately.
Webhooks in Pirsonal deliver personalized and interactive video data to other applications in two scenarios: when a video is ready (“done” status) and when there has been an error with a video (“error” status).
Our call to the webhook includes a JSON-encoded video object with detailed information about the video in its POST body.
You'll learn...
Things you should know before you start
- Only two video statuses are handled through webhooks: “done” and “error”.
- You are responsible for managing videos with “error” status based on your workflow’s requirements.
- Every personalized video and interactive video template or project can have its own webhook.
- All metadata fields will be returned by the webhook if set, including the video’s technical specifications.
- Webhooks can be used with Pirsonal’s video API, UI, and third-party integrations.
Handling videos with “error” status through webhooks
When creating personalized videos and interactive videos with Pirsonal’s software, errors can happen.
The most common scenario is when a real personalized video is not rendered because of a missing media file that our system couldn’t download because it was not found.
When this happens, our personalized video software will change the status of the video from “processing” or “queue” to “error”. In most cases, you’ll also see the reason why the video was not rendered.
Error notifications are shown in the Notifications section, videos list, or when you filter videos by a template.
If you are using webhooks and there has been an error, the system will notify you immediately, the same way it would if the video had been successfully created.
Since we do not have control over your video automation workflow, you need to manage what should happen when an error occurs.
Here are a few recommendations for the most common cases:
If you are using a webhook provided by integrations and data platforms like Zapier, Make, n8n, Automate.io, and Workato, among others, use filters or paths to handle videos with an “error” status. This way, you can define if the video with an error status should be retried or if you should receive an email notification letting you know about this error.
If you are using Pirsonal’s API, we recommend creating a logic that lets you know when there is an error with a video. For example, if the video was not created because of a missing media file, it is advisable to double-check if this happened because of server downtime on the media file’s end. If this was the case, often it is OK to retrigger the personalized video.
However, if there was an error because of a missing file extension or misspelled word, it is not recommended to retrigger the video until this has been fixed. For example, if instead of https://sample-url.com/Mike.mp3, the video software received https://sample-url.com/mike.mp3, or when the URL uses unsupported special characters.
If many consecutive videos show an “error” status, please don’t hesitate to reach out to our support team immediately so that we can investigate the issue further. Simply email help@pirsonal.com and we’ll be glad to help.