QUE Webhooks

With QUE, you can set up webhooks to broadcast your QUE campaign's job additions and changes to other apps, to use in a broader production workflow.

What is a webhook?

Also called a "one-way API" or "reverse API", a webhook is a web request sent from a provider (us) to a consumer (you), usually triggered by some event on the provider's side. For example, when you register a webhook with Dataclay's QUE, you can choose to receive a webhook when a job has its render-status set to done. Then after you set up a server or no-code solution to consume this webhook, you can process it any way you'd like; maybe your workflow sends a Slack message or an aggregated email every hour.

Instead of continuously polling our API, webhooks push data to your application as events happen, making your integrations more efficient and responsive.

Register a webhook

  1. Navigate to que.dataclay.com and click Integrations.

  2. In the QUE Webhook Service section, click New Webhook and fill in the fields to register your webhook event and specific triggers for the event.

    1. Add any additional job fields you'd like to include in the webhook's data payload.
    2. Be sure your Endpoint URL is correct and active to receive data.

  3. Click Register to save.

TIP You are able to send various events to the same URL endpoint, as well as the same event to multiple different URL endpoints.

QUE webhook events reference

Webhooks can be configured to trigger on three QUE events:

  • Job creation

  • Job render-status update

  • Job stream-status update

ClosedQUE event: job created

Triggers when a new job is created, either via the QUE Dash's Campaigns screen (batch or single) or sending a POST to the QUE API at /api/v1/jobs. Here are samples of the webhook data that QUE will send to your application's endpoint.

Single job:

{
  "webhookId": "12a00158-24ff-4ee4-b1ec-e7e302dc098a",
  "orgId": "your-QUE-org-id"
  "jobData": {
    "id": "6851cbad51de6c11a54ed37c",
    "render_status": "ready",
    "stream_status": "pending",
    "campaignId": "6346fd3464882c58e7c3676d",
    "satellite": "64063d162c5b610eb97c6ee0",
    "_createdAt": "2025-06-17T20:10:21.397Z",
  },
  "retryCount": 0, 
  "event_type": "job_created",
  "event_type_triggers": [
    "jobCreated"
  ],
  "event_timestamp": 1750435626270
}

Batch job upload: 

{
  "webhookId": "01dddcdb-8988-494b-bf56-9ef10abffdc5",
  "orgId": "your-QUE-org-id"
  "jobData": [
    {
      "id": "6854439dda26ee887da827ff",
      "render_status": "ready",
      "stream_status": "pending",
      "campaignId": "6346fd3464882c58e7c3676d",
      "_createdAt": "2025-06-19T17:06:37.976Z",
      "satellite": "67e42881109014b7a2eb2346",
    },
    {
      "id": "6854439dda26ee887da82800",
      "render_status": "ready",
      "stream_status": "pending",
      "campaignId": "6346fd3464882c58e7c3676d",
      "_createdAt": "2025-06-19T17:06:37.977Z",
      "satellite": "67e42881109014b7a2eb2346",
    },
    {
      "id": "6854439dda26ee887da82801",
      "render_status": "ready",
      "stream_status": "pending",
      "campaignId": "6346fd3464882c58e7c3676d",
      "_createdAt": "2025-06-19T17:06:37.977Z",
      "satellite": "67e42881109014b7a2eb2346",
      "custom_field1": "Amen brother!",
    }
  ],
  "retryCount": 0,
  "event_type": "job_created",
  "event_type_trigger": "jobCreated",
  "event_timestamp": 1750435626270
}

The webhookID is a unique ID for this webhook event, useful for tracking in your system. Note that if you resend failed events, this ID will be different the next time.

Job data will be one object for single uploads and an array of job objects for batch uploads.

If you've added a custom field from your data in the Register Webhook configuration, it will be included in the data being returned.

ClosedQUE event: job render-status changed

Triggers when a job has changed render-status to done or err* (error state). Learn more about QUE's render-status values.

Single job:

{
  "webhookId": "95d0bd96-0382-4483-b9f2-87c512320ef7",
  "orgId": "your-QUE-org-id"
  "jobData": {
    "id": "68543cb3da26ee887da801a5",
    "render_status": "done",
    "stream_status": "pending",
    "campaignId": "6346fd3464882c58e7c3676d",
    "satellite": "64063d162c5b610eb97c6ee0",
    "_createdAt": "2025-06-19T16:37:07.759Z",
  },
  "retryCount": 1,
  "event_type": "job_render_status_change",
  "event_type_trigger": "done",
  "event_timestamp": 1750435626270
}

The webhook's retryCount value will be 0 on the first attempt, and increment for each attempt until successfully sent.

If the event_type value is job_render_status_change, then the event_type_trigger will return the value of the job's render-status for that event.

ClosedQUE event: job stream-status changed

Triggers when a job has changed stream-status to staged, onstream, or error. This is for use with Dataclay Projector. Learn more about the stream-status values on the Reserved Data Source Names article for Projector.

A sample job's stream-status update webhook:

{
  "webhookId": "95d0bd96-0382-4483-b9f2-87c512320ef7",
  "orgId": "your-QUE-org-id"
  "jobData": {
    "id": "68543cb3da26ee887da801a5",
    "render_status": "done",
    "stream_status": "pending",
    "campaignId": "6346fd3464882c58e7c3676d",
    "satellite": "64063d162c5b610eb97c6ee0",
    "_createdAt": "2025-06-19T16:37:07.759Z",
    "resent": true
  },
  "retryCount": 1, 
  "event_type": "job_render_status_change",
  "event_type_trigger": "done",
  "event_timestamp": 1750435626270
}

If this event has failed too many times, and you've resent via the webhook admin in the QUE Dash, it will be flagged with a resent boolean (true or false) value.

The event_timestamp (in milliseconds) is when the webhook was originally sent. This stays the same for subsequent retries.

Configuring and troubleshooting webhooks

This is not going to be an exhaustive guide on how to set up a server to consume webhooks.We have a first-party Zapier integration built into the QUE Dash, but you are not limited to building your webhooks workflow on Zapier's platform. See our Example webhook receivers below for more resources.

Response

We expect a successful status code (200) to be returned. No body is expected.

Timeout and error policy

  • Our service allows 5 seconds of processing time once we reach 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.

Force resend of failed webhooks

From the webhook admin in the QUE Dash, locate the Actions column, then click Resend Failed Events for the webhook you'd like resent.

All failed webhooks for that specific event and endpoint will be queued to retry in the next 1-2 minutes.

Delete a webhook

From the webhook admin in the QUE Dash, locate the trash can icon in the Actions column for the webhook you'd like to unregister. Deleting the webhook will also clear any failed messages that were triggered by this specific webhook.

Large payloads

If your webhook would return data over 256 KB, it will be split into multiple webhooks. This typically only happens for the Job Created webhook, when uploading job data via the QUE dashboard.

Best practices

Slow, unstable, or incorrectly configured receivers may be disabled automatically. Invalid HTTP responses are treated as failed requests.

To optimize your webhook receivers:

  • Respond quickly with a 200 status:
    • Avoid processing webhooks in the same request to avoid timeouts (offload to another service, for example).
    • Use a queue to handle webhooks after receiving them.
  • Handle potential duplicate events:
    • Prepare for duplicate events if a webhook times out (use the provided webhookId in the payload to keep track).
    • Ensure your endpoint is consistently fast and stable.
  • Events are not guaranteed to be in order, so plan accordingly.
  • Minimize response headers and body:
    • Limit the number and size of returned headers.
    • Consider responding with an empty body.
  • . Use appropriate status codes:
    • Return client error status responses (4xx range) only for misconfigured webhooks.
    • Avoid 500 server error responses for handled events.

Example webhook receivers