Webhook callback
Pass in webhook_url when creating the task. After the task is completed, we will send a POST request to this address.
Request content
Request header:
http
Content-Type: application/json
X-Webhook-Signature: 5f2b8c...Request body:
json
{
"timestamp": 1789632021,
"task": {
"id": "task_3kP9xQ2mZ7aB1cD4eF6gH8jK",
"idempotency_key": "order_10086",
"status": "succeeded",
"output": { "images": ["https://cdn.example.com/outputs/abc.png"] },
"error": null
}
}| Field | Description |
|---|---|
timestamp | Send time (Unix seconds), updated with each send |
task | Task object, the same as returned by the query task. Correspond to your business record through idempotency_key, status is succeeded or failed |
Response and retry
- Returning
2xxmeans reception is successful, please respond within 10 seconds. - Otherwise, it will be sent again after 1 minute, 5 minutes, 30 minutes, 2 hours, and 6 hours, for a total of 6 times.
- The same task may receive multiple pushes, please use
task.idto remove duplicates.
Verify signature
The signing key is obtained from the "Webhook" page of the console.
- Calculate
HMAC-SHA256(secret, raw request body), compare it with the request headerX-Webhook-Signature, and process it only if they are consistent. - Check that the difference between
timestampand the current time does not exceed 5 minutes.
Note: Must be calculated using the original request body received, do not parse JSON first and then serialize.
js
import crypto from 'node:crypto'
function verify(rawBody, signature, secret) {
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
if (expected.length !== signature?.length
|| !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
return false
}
const { timestamp } = JSON.parse(rawBody)
return Math.abs(Date.now() / 1000 - timestamp) < 300
}python
import hashlib
import hmac
import json
import time
def verify(raw_body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, signature or ""):
return False
return abs(time.time() - json.loads(raw_body)["timestamp"]) < 300