Skip to content

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
  }
}
FieldDescription
timestampSend time (Unix seconds), updated with each send
taskTask 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 2xx means 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.id to remove duplicates.

Verify signature ​

The signing key is obtained from the "Webhook" page of the console.

  1. Calculate HMAC-SHA256(secret, raw request body), compare it with the request header X-Webhook-Signature, and process it only if they are consistent.
  2. Check that the difference between timestamp and 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
Copyright © 2026 ModelGo all rights reserved | Technology powered by MoneyGo.ai