Management APIs/Webhooks

Create Webhook

POST

Overview

Create an outbound webhook endpoint that receives job.completed and job.failed events for the authenticated account.

Authentication

All API requests require a Bearer token in the request header.

Authorization: Bearer YOUR_API_KEY

Create and manage API keys from API Keys or use https://www.apimall.ai/api-keys.

Request

API Information

URL: POST https://gateway.apimall.ai/api/v1/webhooks
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
`url`	string	Required	HTTPS endpoint that receives webhook deliveries.
`events`	array	Required	Webhook event types to subscribe to.
`secret_key`	string	Optional	Optional secret used to sign deliveries.
`api_key_id`	integer	Optional	Optional API key scope restriction. Must match the current API key if provided.

Request Example

{
  "url": "https://your-app.example.com/api/webhooks/apimall",
  "events": [
    "job.completed",
    "job.failed"
  ],
  "secret_key": "super-secret-signing-key"
}

Response Example

{
  "success": true,
  "data": {
    "id": 8,
    "url": "https://your-app.example.com/api/webhooks/apimall",
    "events": [
      "job.completed",
      "job.failed"
    ],
    "status": "active",
    "api_key_id": 12,
    "created_at": "2026-03-12T09:55:00.000Z",
    "updated_at": "2026-03-12T09:55:00.000Z"
  },
  "request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}

cURL Example

curl --request POST 'https://gateway.apimall.ai/api/v1/webhooks' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://your-app.example.com/api/webhooks/apimall",
  "events": [
    "job.completed",
    "job.failed"
  ],
  "secret_key": "super-secret-signing-key"
}'

JavaScript Example

const API_KEY = process.env.APIMALL_API_KEY;

const payload = {
  "url": "https://your-app.example.com/api/webhooks/apimall",
  "events": [
    "job.completed",
    "job.failed"
  ],
  "secret_key": "super-secret-signing-key"
};

const response = await fetch('https://gateway.apimall.ai/api/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status} ${response.statusText}`);
}

const data = await response.json();
console.log(data);

Response Parameters

Parameter	Type	Description
`success`	boolean	Whether the request completed successfully.
`data.id`	integer	id field returned by the API.
`data.url`	string	URL associated with the returned resource, such as a hosted file URL or a webhook destination URL.
`data.events`	array	Webhook event types subscribed by this endpoint.
`data.status`	string	Current status value returned by the API. Generation task endpoints use normalized values such as `pending`, `processing`, `completed`, `failed`, or `unknown`; management endpoints may return resource states such as `created`, `revoked`, or `active`.
`data.api_key_id`	integer	API key identifier associated with the returned resource when applicable.
`data.created_at`	string	Creation timestamp for the returned resource or task record.
`data.updated_at`	string	Last update timestamp for the returned resource or task record.
`request_id`	string	Request identifier for debugging and support.

Error Response Example

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid webhook URL"
  },
  "request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}

Integration Notes

Store your API key on the server side only.

Error Codes

Common Error Codes

Status Code	Description
200	Request successful
400	Invalid request parameters
401	API key required or invalid API key
403	API access not approved or request made on a non-gateway host
429	Rate limit exceeded or too many concurrent jobs
500	Internal server error

Request

curl --location --request POST 'https://gateway.apimall.ai/api/v1/webhooks' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "url": "https://your-app.example.com/api/webhooks/apimall",
  "events": [
    "job.completed",
    "job.failed"
  ],
  "secret_key": "super-secret-signing-key"
}'

{
  "success": true,
  "data": {
    "id": 8,
    "url": "https://your-app.example.com/api/webhooks/apimall",
    "events": [
      "job.completed",
      "job.failed"
    ],
    "status": "active",
    "api_key_id": 12,
    "created_at": "2026-03-12T09: 55: 00.000Z",
    "updated_at": "2026-03-12T09: 55: 00.000Z"
  },
  "request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}