Receive a task completion notification

POSTtask.completedSent to your registered callback address

Chenvoya sends task.completed when a task reaches succeeded, failed or cancelled.

Any 2xx response confirms receipt; other answers and timeouts are retried on schedule.
Verify Chenvoya-Signature before you handle the body.
Delivery is at least once: deduplicate on event_id in the verified body.
The event has no download link; read the task for the result.

Headers

#Chenvoya-Event-IdstringRequired

A convenience copy of the event ID. This header is not covered by the signature. After verifying the signature, deduplicate using event_id inside the signed body.

Formatuuid

#Chenvoya-SignaturestringRequired

The notification signature contains t and v1. Check the timestamp as described in Callbacks, calculate HMAC-SHA256 over the original body bytes and compare in constant time.

Request bodyapplication/json · Required

#event_idstringRequired

The unique event ID inside the signed body. Deduplicate on this field after successful signature verification.

Formatuuid

#objectstringRequired

The notification object type, always event.

Alwaysevent

#typestringRequired

Whether this notification reports task completion or billing settlement.

task.completedThe task reached a final state

task.billing_settledThe task billing has been settled

#schema_versionintegerRequired

The notification format version, currently the integer 1.

Always1

#created_atintegerRequired

Event creation time in whole Unix seconds. Check it separately from each delivery attempt's signature timestamp.

Range≥ 0

#dataobjectRequired

The customer task snapshot saved when this event was created.

9 child fields

#task_idstringRequired

The platform Task ID belonging to your team.

Length4–128CharactersA–Z a–z 0–9 _ -

#request_idstringRequired

The Request ID associated with task creation.

Length4–128CharactersA–Z a–z 0–9 _ -

#billing_correlation_idstringRequired

The billing correlation ID associated with task creation.

Length4–128CharactersA–Z a–z 0–9 _ -

#modelstringRequired

The public model ID used for this task.

dreamina-seedance-2-0-260128Seedance 2.0

dreamina-seedance-2-0-fast-260128Seedance 2.0 Fast

dreamina-seedance-2-0-mini-260615Seedance 2.0 Mini

#statusstringRequired

The final task status: succeeded, failed or cancelled.

succeededSucceeded

failedFailed

cancelledCancelled

#delivery_statusstringRequired

Result delivery status when the event snapshot was saved.

pendingNot yet delivered

materializingPreparing the download

availableReady to download

output_unavailableResult unavailable

#errorobjectRequiredNullable

The task error object, or null when there is no error.

3 child fields

#codestringRequired

A code your application can use to handle the error.

no_common_asset_routeAssets temporarily unavailable

asset_not_readyA referenced asset is still processing

asset_review_timeoutAsset review timed out

route_misconfiguredService configuration error

route_temporarily_unavailableTemporarily unavailable

generation_expiredGeneration expired

generation_failedGeneration failed

input_fetch_failedAn input could not be downloaded from its URL

input_url_not_allowedAn input URL is not allowed

input_too_largeAn input exceeds its size limit

input_unsupportedAn input format, dimensions or duration is unsupported

input_rejectedAn input did not pass content review

input_preparation_failedThe inputs could not be prepared in time

input_duration_exceededThe combined input duration exceeds the model limit

#messagestringRequired

A readable explanation of the error.

Length1–1024

#detailsobject

Optional fields with more information about the error.

1 child fields

#content_indexinteger

Zero-based position of the failed input in the original content array, including text items.

Range0–50

#settlement_statusstringRequired

The billing settlement status when the event snapshot was saved.

reservedReserved

pendingPending

reconciliation_requiredUnder review

settledSettled

settled_with_receivableSettled - amount due

#final_actual_coststringRequiredNullable

The final charge as a USD string with six decimal places, or null until determined.

Format6 decimal places

Example body

JSON

{
  "event_id": "7f9c2ba4-e88f-4d2b-9a2f-0c3e5b8d1a64",
  "object": "event",
  "type": "task.completed",
  "schema_version": 1,
  "created_at": 1793167400,
  "data": {
    "task_id": "task_32ae2a5177b310d3bc1ec83a98f63889",
    "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
    "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
    "model": "dreamina-seedance-2-0-260128",
    "status": "succeeded",
    "delivery_status": "available",
    "error": null,
    "settlement_status": "pending",
    "final_actual_cost": null
  }
}

Your response

The notification was received. Any 2xx response confirms delivery; other responses and timeouts cause scheduled retries.

Retry schedule

after 10 seconds
after 1 minute
after 5 minutes
then every hour
for up to 7 days

Verify the signature

The full signature, deduplication and age rules are on Verify callback signatures.

Python

import base64
import hashlib
import hmac
import time

def verify(signing_secret, header, body):
    fields = {}
    for item in header.split(","):
        name, _, value = item.strip().partition("=")
        fields[name] = value
    t, v1 = fields.get("t", ""), fields.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False
    key = base64.urlsafe_b64decode(signing_secret + "=" * (-len(signing_secret) % 4))
    signed = b"chenvoya.v1." + t.encode() + b"." + body
    expected = hmac.new(key, signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

Receive callbacks Verify callback signatures

Receive a task completion notification

Headers

Request bodyapplication/json · Required

Your response

Retry schedule

Verify the signature

Related guides