Batch Webhooks: Receive Signed Task Completion Events

Batch Webhooks send one HTTP POST to your root-level webhook_url whenever an accepted batch item reaches a successful or failed terminal state.

Batch Webhooks are separate from the single-task callback_url workflow. They use an account-level signing secret and X-Apixo-Signature verification.

Lifecycle

Get the account-level secret with your API key
        ↓
Store the secret in your server-side secret manager
        ↓
Submit a batch with webhook_url
        ↓
An accepted item succeeds or fails
        ↓
APIXO signs and sends the webhook
        ↓
Verify, deduplicate, and process the event

No separate webhook account is required. The secret belongs to the account that owns the authenticated API key, and API keys under the same account share that account-level signing secret.

Step 1: Get the signing secret

GET https://api.apixo.ai/api/v1/webhooks/secret

curl "https://api.apixo.ai/api/v1/webhooks/secret" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "version": 1,
    "secret": "YOUR_WEBHOOK_SIGNING_SECRET"
  }
}

The secret is a shared signing secret:

APIXO uses it to calculate an HMAC-SHA256 signature for each webhook request.
Your service uses it to verify that the request came from APIXO and that its body was not modified.
Do not send the secret back in a batch request or webhook response.
The webhook body is not an encrypted payload. HTTPS encrypts the transport; the secret authenticates the sender and protects message integrity.
Store the secret only in a server-side KMS, Secret Manager, or protected environment variable. Never expose it in a client application, source repository, or logs.

Step 2: Submit a batch with webhook_url

Set webhook_url at the root of the batch request:

curl -X POST "https://api.apixo.ai/api/v1/generateTask/seedream-4-5/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: batch-20260915-002" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://merchant.example.com/webhooks/apixo",
    "items": [
      {
        "client_item_id": "order-1003",
        "idempotency_key": "order-1003-v1",
        "input": {
          "mode": "text-to-image",
          "prompt": "A minimalist mountain coffee shop"
        }
      }
    ]
  }'

webhook_url must be a publicly reachable HTTPS address. Each batch retains its signing-secret version, so a secret rotation does not break verification for already accepted batches.

Step 3: Receive a webhook

APIXO sends these headers:

POST https://merchant.example.com/webhooks/apixo
Content-Type: application/json
X-Apixo-Event-Id: evt_123
X-Apixo-Timestamp: 1789459200
X-Apixo-Signature: v1,2b1c...

Header	Description
`X-Apixo-Event-Id`	Unique delivery event ID. Use it for receiver-side deduplication.
`X-Apixo-Timestamp`	Unix timestamp in seconds. Use it to limit your replay window.
`X-Apixo-Signature`	`v1,` followed by a hexadecimal HMAC-SHA256 signature.

Successful task payload

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_123",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://cdn.example.com/output.jpg\"]}"
  },
  "batch": {
    "batchId": "batch_123",
    "clientItemId": "order-1003"
  }
}

Failed task payload

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_987",
    "state": "failed",
    "failCode": "CONTENT_VIOLATION",
    "failMsg": "Content violates usage policy"
  },
  "batch": {
    "batchId": "batch_123",
    "clientItemId": "order-1004"
  }
}

Webhook payload fields

Field	Type	Description
`code`	integer	Webhook envelope code. `200` does not mean generation succeeded; inspect `data.state`.
`message`	string	Webhook envelope message. `success` is used for normal terminal payloads.
`data.taskId`	string	Completed platform task ID. You can use it with Single Tasks > Status Task.
`data.state`	string	Terminal business state. `success` means generation succeeded; `failed` means it failed.
`data.resultJson`	string	Usually present on success. JSON string containing public model output, such as `resultUrls`.
`data.failCode`	string	Usually present on failure. Programmatic failure code.
`data.failMsg`	string	Usually present on failure. Developer-facing failure explanation.
`batch.batchId`	string	Batch that contains this task.
`batch.clientItemId`	string	Caller-provided item locator. Use it to associate the event with your order or job.

Step 4: Verify, deduplicate, and respond

The signed bytes are exactly:

{eventId}.{timestamp}.{rawRequestBody}

Calculate the signature as:

hex(HMAC-SHA256(secret, signingPayload))

rawRequestBody is the original HTTP body bytes. Do not parse, format, or serialize JSON again before signature verification.

Node.js / Express verification example

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const webhookSecret = process.env.APIXO_WEBHOOK_SECRET;

app.post('/webhooks/apixo', express.raw({ type: 'application/json' }), async (req, res) => {
  const eventId = req.get('X-Apixo-Event-Id');
  const timestamp = req.get('X-Apixo-Timestamp');
  const signatureHeader = req.get('X-Apixo-Signature') || '';
  const signature = signatureHeader.startsWith('v1,') ? signatureHeader.slice(3) : '';
  const nowSeconds = Math.floor(Date.now() / 1000);

  if (!eventId || !timestamp || !signature || Math.abs(nowSeconds - Number(timestamp)) > 300) {
    return res.status(400).send('Invalid webhook headers');
  }

  const signingPayload = Buffer.concat([
    Buffer.from(`${eventId}.${timestamp}.`, 'utf8'),
    req.body,
  ]);
  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(signingPayload)
    .digest('hex');

  const receivedBytes = Buffer.from(signature, 'hex');
  const expectedBytes = Buffer.from(expected, 'hex');
  if (receivedBytes.length !== expectedBytes.length
      || !crypto.timingSafeEqual(receivedBytes, expectedBytes)) {
    return res.status(401).send('Invalid signature');
  }

  // Persist and deduplicate eventId with a database uniqueness constraint or a TTL-backed store.
  const payload = JSON.parse(req.body.toString('utf8'));
  if (payload.data.state === 'success') {
    // Find your order by payload.batch.clientItemId, then process the result asynchronously.
  } else {
    // Record payload.data.failCode / failMsg and update your failure state.
  }

  return res.status(204).end();
});

Process every event in this order:

Preserve the raw body and read the three X-Apixo-* headers.
Check that the timestamp is within your allowed window; this example uses five minutes.
Calculate the HMAC with the account secret and compare signatures in constant time.
Persist and deduplicate X-Apixo-Event-Id.
Only then parse JSON, update orders, or enqueue downstream work.
Return any HTTP 2xx once the event is safely recorded.

Do not verify a parsed or reserialized JSON body; even a byte-level formatting change invalidates the signature. Deduplicate by X-Apixo-Event-Id, not only by taskId.

Retry and recovery

Any HTTP 2xx is a successful delivery.
A non-2xx response, network error, or timeout schedules a retry.
Retry intervals are 1 minute → 5 minutes → 30 minutes → 2 hours → 6 hours. Including the first delivery, there are at most six attempts.
Keep Batch Status and Single Tasks > Status Task as recovery and reconciliation paths.

Rotate or revoke a secret

Rotate

POST https://api.apixo.ai/api/v1/webhooks/secret/rotate

Newly submitted batches use the new secret. Already accepted batches continue using the previous secret during a seven-day grace period, so receivers should support both secrets during that time.

Emergency revoke

POST https://api.apixo.ai/api/v1/webhooks/secret/revoke

Revocation suppresses all outstanding deliveries for the account and revokes existing secrets. To resume batch webhooks, get a new secret and submit new batches with webhook_url.

Production checklist

Your endpoint is public HTTPS and returns a 2xx quickly.
The signing secret is stored securely and never exposed to client code or logs.
The receiver verifies the raw body before parsing JSON.
The receiver checks timestamp freshness and persistently deduplicates X-Apixo-Event-Id.
Slow work runs in a queue or worker rather than blocking the HTTP response.
You have Batch Status or Status Task reconciliation for missed events.

​Lifecycle

​Step 1: Get the signing secret

​Step 2: Submit a batch with webhook_url

​Step 3: Receive a webhook

​Successful task payload

​Failed task payload

​Webhook payload fields

​Step 4: Verify, deduplicate, and respond

​Node.js / Express verification example

​Retry and recovery

​Rotate or revoke a secret

​Rotate

​Emergency revoke

​Production checklist

Lifecycle

Step 1: Get the signing secret

Step 2: Submit a batch with webhook_url

Step 3: Receive a webhook

Successful task payload

Failed task payload

Webhook payload fields

Step 4: Verify, deduplicate, and respond

Node.js / Express verification example

Retry and recovery

Rotate or revoke a secret

Rotate

Emergency revoke

Production checklist