Skip to main content

Webhooks

Instead of polling Get Result, you can pass a webhook URL when you submit a task. Once the task completes or fails, its final state is sent to that URL.

Subscribing​

Add webhook to the submit request body:

{
  "params": {},
  "webhook": {
    "url": "https://my-service.picsart.com/hooks/tasks?correlationId=order-42"
  }
}
  • Use an https URL with a publicly trusted certificate. Plain http is allowed only for tasks submitted through the internal base URL.
  • The URL is called exactly as given, query string included, so you can use it to carry your own correlation IDs.

A URL that doesn't meet these rules fails the submit with 400 invalid_webhook_url, and no task is created.

Request​

POST <your webhook URL>
Content-Type: application/json
x-task-id: <TASK_ID>

Completed task​

{
  "workflow": "example-task",
  "userId": 111,
  "params": {}, // the params the task was submitted with
  "id": "<TASK_ID>",
  "status": "COMPLETED",
  "created": "2026-10-02T10:00:00Z",
  "updated": "2026-10-02T10:00:05Z",
  "result": {}, // task result
  "usage": { // credits charged, if any; same shape as `usage` in Get Result
    "credits": 2,
    "details": []
  }
}

Failed task​

{
  "workflow": "example-task",
  "userId": 111,
  "params": {},
  "id": "<TASK_ID>",
  "status": "FAILED",
  "created": "2026-10-02T10:00:00Z",
  "updated": "2026-10-02T10:00:05Z",
  "result": {
    "reason": "bad_input",
    "message": "Image is too large",
    "statusCode": 422,
    "details": {} // only when the task provided details
  }
}

reason, message and statusCode are always present, matching the error Get Result returns for the same task.

Delivery​

  • Respond with any 2xx status within 5 seconds. The response body is ignored.
  • Each webhook is attempted once. A non-2xx response, a redirect, a timeout or a connection error is not retried. If you miss a webhook, use Get Result to fetch the task's state.
  • Webhooks are not signed: a request carries nothing that proves where it came from, so anyone who knows the URL can call it.