A QUE webhook is a message QUE sends to your server when something happens to a job, so your own system hears about it without asking. You register it once in the QUE Dash, pick which of three events you want, and QUE posts a small JSON payload to your endpoint each time that event fires. This page covers how to register one, what each of the three events sends, what the fields mean, and what our docs tell you to do on the receiving end.
It is written for a developer, a producer with a developer on call, or someone wiring QUE into a no-code tool. If your question is the general theory of handling callbacks from any render service, our page on handling webhook callbacks in a production application covers that. Here we stay on QUE’s own events and payloads.
What a QUE webhook is for, and how to register one
Our docs define a webhook as a web request sent from a provider, which is us, to a consumer, which is you. It is triggered by some event on the provider’s side. People also call it a one-way API or a reverse API. The point is the direction. Instead of your application asking QUE over and over whether a job has finished, QUE pushes the news to you when it happens. Our docs describe this as more efficient and more responsive than continuous polling, and that is the whole reason to prefer one.
The example in our docs is the render-status event. You register a webhook to fire when a job’s render status is set to done. Then you set up a server or a no-code tool to receive it, and you do whatever you like with it. The docs suggest a Slack message, or an aggregated email every hour. What you do with the message is up to you.
Registration takes place in the browser. Go to que.dataclay.com and click Integrations. In the QUE Webhook Service section, click New Webhook. Fill in the fields to register your webhook event and the specific triggers for that event. Add any additional job fields you want included in the payload. Make sure your Endpoint URL is correct and active, because QUE will send real requests to it. Then click Register to save.
Registration in Dash
How to register a QUE webhook
-
Go to IntegrationsGo to que.dataclay.com and click Integrations.
-
Click New WebhookIn the QUE Webhook Service section, click New Webhook.
-
Fill in the fieldsFill in the fields to register your webhook event and the specific triggers for that event.
-
Add extra job fieldsAdd any additional job fields you want included in the payload.
-
Click RegisterClick Register to save.
Two pieces of that form deserve a sentence each. The extra job fields are how you get your own data into the message. A job’s properties include whatever customization data you stored, and a field you add here is included in the data being returned. If your downstream system needs a customer ID or a campaign label that lives on the job, add it at registration so you do not have to look the job up afterward. The Endpoint URL is the other piece. The docs say to be sure it is correct and active, which is worth taking literally. A typo here means every event for this webhook goes to the wrong place or fails.
Our docs also include a tip that saves you from over-building. You can send various events to the same endpoint URL, and you can send the same event to multiple different endpoint URLs. So one receiving route can handle all three events and branch on the event type, or you can register separate webhooks that point at separate routes. The first is simpler to deploy. The second keeps each handler small. Both are allowed.
QUE also has a first-party Zapier integration built into the QUE Dash, so you do not need your own server to start. If you want to compare that path with calling the API directly, see Zapier or the QUE API for creating video jobs. Our docs list four places to point a test webhook while you build a receiver: ngrok for a local machine, Zapier for no-code, your existing API server, and webhook.site as a free online catcher. Any of them will show you a real payload before you write any parsing code.
The three events and what each one sends
A webhook can be configured to trigger on three QUE events. These are job creation, job render-status update, and job stream-status update. Each message shares one envelope and differs in what it says inside the job data and which trigger it names.
The envelope fields, as they appear in our samples, are these. The webhookId is a unique ID for this webhook event, useful for tracking in your system. The orgId is your QUE organization ID. The jobData holds the job or jobs involved. The retryCount says which attempt this is. The event_type names the event. The event_trigger field, spelled event_type_trigger in the render-status and batch samples, names the specific trigger. The event_timestamp is a number in milliseconds. Read the samples in the docs closely, because the single-job job-created sample shows the trigger key as an array named event_type_triggers, while the batch sample shows a plain event_type_trigger. If you parse these in code, accept both spellings on that event, or test against a real delivery and write to what you see.
Job created. This fires when a new job is created. That happens either from the QUE Dash’s Campaigns screen, as a batch or a single job, or when something sends a POST to the QUE API at /api/v1/jobs. So it covers both the hand-entered case and the programmatic one. The event_type value is job_created, and the trigger is jobCreated. The jobData in the sample carries the job’s id, its render_status (ready), its stream_status (pending), its campaignId, its satellite and a _createdAt time.
The shape of jobData depends on how the jobs arrived. For a single upload, it is one object. For a batch upload, it is an array of job objects. This matters for your parser, because a handler written for one object will break on an array, and the reverse. The simplest safe habit is to check whether jobData is an array before you read it. In the batch sample from our docs, three jobs arrive in a single message, and one of them carries a custom field that was added in the registration form. That is the extra-field feature working as described.
Job render-status changed. This fires when a job changes its render status to done or to an error state. The docs write the error state as err followed by an asterisk, meaning the status begins with err. To learn what each status means, see our page on QUE job states. The event_type value is job_render_status_change, and the event_type_trigger returns the job’s render status for that event. So if the job went to done, the trigger reads done. That lets one route tell a finished render from a failed one without reading the whole job.
Job stream-status changed. This fires when a job’s stream status changes to staged, onstream or error. It is for use with Dataclay Projector, which our docs describe as a tool for rendering and distributing your videos. Our docs point to the Projector article on reserved data source names for the stream-status values, and we cover the pipeline in how a render becomes a live video. If you do not use Projector, you can ignore this event entirely. The sample in the docs for this event shows the same fields as the others, along with an extra boolean named resent, which we explain below.
Here is a trimmed single-job render-status payload, built from the field names in our docs sample, to show the shape. The values are placeholders.
{
"webhookId": "95d0bd96-0382-4483-b9f2-87c512320ef7",
"orgId": "your-QUE-org-id",
"jobData": {
"id": "68543cb3da26ee887da801a5",
"render_status": "done",
"stream_status": "pending",
"campaignId": "6346fd3464882c58e7c3676d",
"satellite": "64063d162c5b610eb97c6ee0"
},
"retryCount": 0,
"event_type": "job_render_status_change",
"event_type_trigger": "done",
"event_timestamp": 1750435626270
}Notice what is not in the payload. There is no output file and no video URL. The job data in the samples describes the job’s state and identifiers. If your workflow needs the finished file, our docs do not say that the webhook carries it, so treat the message as a signal to go and fetch what you need. A reasonable way to do that is to use the job ID from the message with the API, as covered in getting started with the QUE API.
The retryCount field and the event_timestamp field are worth a closer look, since they describe the delivery. Per our docs, retryCount is 0 on the first attempt and increments for each attempt until the message is successfully sent. The event_timestamp is in milliseconds and is when the webhook was originally sent, and it stays the same for subsequent retries. So a message with a retryCount of 1 and an old event_timestamp is a second attempt at the same event, not a new event.
Receiving them: responses, timeouts, resends and a worked example
Everything in this section is what our docs state, and we stop where they stop. They say this is not an exhaustive guide to building a webhook server, and it is not one here either.
On the response, we expect a successful status code, 200, to be returned. No body is expected. QUE allows 5 seconds of processing time once it reaches your servers. Any failed attempts are retried once, approximately 30 seconds apart. All failed webhooks are placed in a new collection, and you can force retrying them from the webhook admin in the QUE Dash. Beyond those statements, we do not describe other delivery behavior, because our saved docs do not.
The force resend works like this. In the webhook admin in the QUE Dash, find the Actions column, then click Resend Failed Events for the webhook you want resent. All failed webhooks for that specific event and endpoint are queued to retry in the next one to two minutes. Our docs add a detail you will see in a payload. If an event failed too many times and you resent it through the webhook admin, it is flagged with a resent value of true. That is the resent boolean from the stream-status sample. Also note what the docs say about the ID. If you resend failed events, the webhookId will be different the next time. So do not assume a webhookId stays the same across a resend.
To delete a webhook, go to the webhook admin in the QUE Dash and find the trash can icon in the Actions column for the webhook you want to unregister. Deleting the webhook also clears any failed messages that were triggered by that specific webhook. So if you are retiring an integration, delete the webhook and the leftover failures go with it.
Large payloads have their own rule. If a webhook would return more than 256 KB of data, it is split into multiple webhooks. The docs tie this to the Job Created webhook when you upload job data through the QUE Dash. The practical meaning is that a big batch upload may reach you as several messages, not one, so do not assume one message equals one upload.
Our best-practice list for receivers is short, and each item carries its reason. Respond quickly with a 200 and avoid doing the processing in the same request, because a slow handler risks a timeout. Offload the work to another service, or use a queue to handle webhooks after receiving them. Handle potential duplicate events, because a webhook that times out can be delivered again, and the webhookId in the payload is what you use to keep track. Keep your endpoint consistently fast and stable, since slow, unstable or incorrectly configured receivers may be disabled automatically, and invalid HTTP responses are treated as failed requests. Do not rely on order, because events are not guaranteed to arrive in order. Minimize response headers and body, and consider replying with an empty body. Return client error statuses in the 4xx range only for misconfigured webhooks, and avoid 500 errors for events you handled.
Receiver best practices
What to do on the receiving end
- Respond quickly with a 200 and avoid doing the processing in the same request
- Offload the work to another service, or use a queue to handle webhooks after receiving them
- Handle potential duplicate events using the webhookId in the payload to keep track
- Keep your endpoint consistently fast and stable
- Do not rely on order, because events are not guaranteed to arrive in order
- Return client error statuses in the 4xx range only for misconfigured webhooks, and avoid 500 errors for events you handled
A hypothetical example, labeled as one, puts these together. A producer runs a monthly batch of personalized videos and wants a message in a team channel when each one finishes or fails. They register one webhook on the render-status event, add the customer name as an extra job field, and point it at a no-code catcher. The handler reads event_type_trigger. If it says done, it posts a success line with the customer name. If it starts with err, it posts a failure line with the job ID so someone can open the job in the Dash. The handler replies 200 immediately and does the posting afterward. It stores each webhookId it has seen, so a repeated delivery does not post twice.
Who should skip webhooks? If you check on a batch once, by hand, after it finishes, the Dash already shows you every job’s status and a webhook adds nothing. If you only have one job to track at a time, polling the API on a timer is simpler to build than a receiving endpoint. Webhooks earn their place when something else in your pipeline should start the moment a job changes state, and when you can run an endpoint that stays up.
The bottom line is this. Register the webhook in the QUE Dash under Integrations, choose from the three events, and add only the job fields you need. Write your parser to accept both a single object and an array in jobData. Reply 200 fast, deduplicate on webhookId, and never count on order. Treat each message as a nudge to go and look, and keep the endpoint boring and quick. The product pages for QUE and Projector explain the systems around it.
Those are the main points from the docs. Here are the questions that decide whether a webhook fits your setup.
Frequently Asked Questions
What events can a QUE webhook send?
Our docs list three. Job creation fires when a new job is made, either from the QUE Dash Campaigns screen as a single job or a batch, or by a POST to the QUE API at /api/v1/jobs. Job render-status update fires when a job’s render status changes to done or an error state. Job stream-status update fires when the stream status changes to staged, onstream or error, and it is meant for Projector.
Where do I register a QUE webhook?
Go to que.dataclay.com and click Integrations. In the QUE Webhook Service section, click New Webhook, then fill in the fields to register your event and its specific triggers. Add any extra job fields you want in the payload, confirm the Endpoint URL is correct and active, and click Register to save. You can send different events to one URL, or one event to several URLs.
What does a QUE webhook payload contain?
The samples in our docs show a webhookId, your orgId, a jobData section, a retryCount, an event_type, a trigger value and an event_timestamp in milliseconds. The jobData includes the job id, render_status, stream_status, campaignId, satellite and creation time. Any custom field you added at registration is included too. For a single upload jobData is one object, and for a batch it is an array.
What response does QUE expect from my endpoint?
QUE expects a successful status code, 200, with no body. It allows 5 seconds of processing time once it reaches your server. Our docs advise replying quickly and handling the real work afterward, for example through a queue. Invalid HTTP responses are treated as failed requests, and slow, unstable or incorrectly configured receivers may be disabled automatically.
What happens when my endpoint fails to receive a webhook?
Per our docs, failed attempts are retried once, approximately 30 seconds apart. All failed webhooks are placed in a new collection. From the webhook admin in the QUE Dash you can click Resend Failed Events in the Actions column, and the failed events for that event and endpoint are queued to retry in the next one to two minutes. Resent events carry a resent flag, and the webhookId will be different.
How do I stop duplicate webhooks from causing double actions?
Our docs say to prepare for duplicate events if a webhook times out, and to use the webhookId in the payload to keep track of what you have handled. Store each ID you process and skip any repeat. Remember that a resend through the Dash gives a different webhookId, so also look at the job ID and the trigger value when the same job appears again.
Can I delete a QUE webhook, and what happens to its failed messages?
Yes. In the webhook admin in the QUE Dash, click the trash can icon in the Actions column for the webhook you want to unregister. Deleting it also clears any failed messages that were triggered by that specific webhook. If you only want to pause an integration, our docs do not describe a pause option, so the choices they describe are delete or leave it registered.
