Skip to main content
This feature is currently in beta and requires the parallel-beta: webhook-2025-08-12 header when using the Task API.
Prerequisites: Before implementing Task API webhooks, read Webhook Setup & Verification for critical information on:
  • Recording your webhook secret
  • Verifying HMAC signatures
  • Security best practices
  • Retry policies
This guide focuses on Task API-specific webhook events and payloads.

​
Overview

Webhooks allow you to receive real-time notifications when your task runs complete, eliminating the need for constant polling—especially useful for long-running or research-intensive tasks.

​
Setup

To register a webhook for a task run, include a webhook parameter in your task run creation request: 
curl --request POST \
  --url https://api.parallel.ai/v1/tasks/runs \
  --header "Content-Type: application/json" \
  --header "parallel-beta: webhook-2025-08-12" \
  --header "x-api-key: $PARALLEL_API_KEY" \
  --data '{
    "task_spec": {
      "output_schema": "Find the GDP of the specified country and year"
    },
    "input": "France (2023)",
    "processor": "core",
    "metadata": {
      "key": "value"
    },
    "webhook": {
      "url": "https://your-domain.com/webhooks/parallel",
      "event_types": ["task_run.status"]
    }
  }'

​
Webhook Parameters

ParameterTypeRequiredDescription
urlstringYesYour webhook endpoint URL. Can be any domain.
event_typesarray[string]YesCurrently only ["task_run.status"] is supported.

​
Event Types

Task API currently supports the following webhook event type:
Event TypeDescription
task_run.statusEmitted when a task run completes (success or failure)

​
Webhook Payload Structure

Each webhook payload contains:
  • timestamp: ISO 8601 timestamp of when the event occurred
  • type: Event type
  • data: Event-specific payload. For the ‘task_run.status’ event, it is the complete Task Run object

​
Example Payloads

Success
{
  "timestamp": "2025-04-23T20:21:48.037943Z",
  "type": "task_run.status",
  "data": {
    "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654",
    "status": "completed",
    "is_active": false,
    "warnings": null,
    "error": null,
    "processor": "core",
    "metadata": {
      "key": "value"
    },
    "created_at": "2025-04-23T20:21:48.037943Z",
    "modified_at": "2025-04-23T20:21:48.037943Z"
  }
}
Failure
{
  "timestamp": "2025-04-23T20:21:48.037943Z",
  "type": "task_run.status",
  "data": {
    "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654",
    "status": "failed",
    "is_active": false,
    "warnings": null,
    "error": {
      "message": "Task execution failed",
      "details": "Additional error details"
    },
    "processor": "core",
    "metadata": {
      "key": "value"
    },
    "created_at": "2025-04-23T20:21:48.037943Z",
    "modified_at": "2025-04-23T20:21:48.037943Z"
  }
}

​
Security & Verification

For information on HMAC signature verification, including code examples in multiple languages, see the Webhook Setup Guide - Security & Verification section.

​
Retry Policy

See the Webhook Setup Guide - Retry Policy for details on webhook delivery retry configuration.

​
Best Practices

For webhook implementation best practices, including signature verification, handling duplicates, and async processing, see the Webhook Setup Guide - Best Practices section.