Webhooks

Webhooks allow you to receive real-time notifications when specific events occur in your account, such as when a video upload is completed or when a connected account requires re-authentication.

Base URL

https://api.multi-upload-tool.com/api/v1

Authentication

All requests require an API Token in the header: x-api-key: YOUR_API_TOKEN

Supported Events

The following events can trigger a webhook notification:

Event Name	Description
`upload.completed`	Triggered when a video or post is successfully published to a platform.
`upload.failed`	Triggered when a publication fails.
`connected_account.connected`	Triggered when a new social media account is connected.
`connected_account.disconnected`	Triggered when a social media account is disconnected.
`connected_account.expired`	Triggered when an account’s access token expires and requires reconnection.
`connected_account.refresh_failed`	Triggered when the system fails to refresh an expired access token automatically.
`subscription.created`	Triggered when a new subscription is created.
`subscription.updated`	Triggered when a subscription is updated (e.g. plan change).
`subscription.cancelled`	Triggered when a subscription is cancelled.
`subscription.expired`	Triggered when a subscription expires.
`suggestion.created`	Triggered when a new suggestion or feedback item is created.
`suggestion.updated`	Triggered when the status of a suggestion is updated (e.g. approved, implemented).
`security.login`	Triggered when a user logs in to the account (security audit).
`team.invite`	Triggered when a new member is invited to the team.

Payload Structure

All webhook requests are sent as POST requests with a JSON body. The payload follows a standard envelope format:


{
  "id": "evt_V1StGXR8_Z5jdHi6B-myT",
  "event": "upload.completed",
  "createdAt": "2026-01-01T12:00:00.000Z",
  "data": {
    // Event-specific data
  }
}

Example: Upload Completed Payload


{
  "id": "evt_abc123",
  "event": "upload.completed",
  "createdAt": "2026-01-01T12:00:00.000Z",
  "data": {
    "uploadId": 123,
    "platform": "tiktok",
    "status": "completed",
    "metadata": {
      "videoId": "73123456789",
      "shareUrl": "https://www.tiktok.com/@user/video/73123456789"
    }
  }
}

Security & Verification

To ensure that the webhook requests are coming from us, we include a signature in the headers. You should verify this signature using your webhook secret.

Headers

Header	Description
`X-Webhook-Event`	The name of the event (e.g., `upload.completed`).
`X-Webhook-ID`	The unique ID of the event.
`X-Webhook-Timestamp`	The timestamp of the request.
`X-Webhook-Signature`	The HMAC SHA-256 signature.

Verifying the Signature

The signature is generated using HMAC SHA-256 with your webhook secret. The data to sign is constructed as: timestamp + "." + JSON.stringify(payload)

Node.js Example


const crypto = require('crypto');
 
function verifySignature(payload, signature, secret, timestamp) {
  const data = `${timestamp}.${JSON.stringify(payload)}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(data)
    .digest('hex');
    
  return signature === expectedSignature;
}

Python Example


import hmac
import hashlib
 
def verify_signature(payload, signature, secret, timestamp):
    data = f"{timestamp}.{payload}"
    expected_signature = hmac.new(
        secret.encode(),
        data.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected_signature)

Manage Webhooks

List Webhooks

Retrieve all configured webhooks for your account.

Endpoint

GET /webhooks

Example Request


curl -X GET "https://api.multi-upload-tool.com/api/v1/webhooks" \
  -H "x-api-key: YOUR_API_TOKEN"

Example Response


{
  "success": true,
  "data": [
    {
      "id": 1,
      "url": "https://your-api.com/webhooks",
      "events": ["upload.completed", "upload.failed"],
      "isActive": true,
      "createdAt": "2026-01-01T10:00:00.000Z"
    }
  ]
}

Create Webhook

Endpoint

POST /webhooks

Body Parameters

Parameter	Type	Required	Description
`url`	string	Yes	The HTTPS URL where the webhook payloads will be sent.
`events`	string[]	Yes	Array of event names to subscribe to (e.g., `upload.completed`).
`secret`	string	No	Optional custom secret for signature verification. If omitted, one will be generated for you.

Example Request


curl -X POST "https://api.multi-upload-tool.com/api/v1/webhooks" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-api.com/webhooks",
    "events": ["upload.completed", "upload.failed", "connected_account.expired"],
    "secret": "my-custom-secret-key"
  }'

Example Response


{
  "success": true,
  "data": {
    "id": 2,
    "url": "https://your-api.com/webhooks",
    "events": ["upload.completed", "upload.failed", "connected_account.expired"],
    "secret": "my-custom-secret-key",
    "isActive": true,
    "createdAt": "2026-01-01T12:00:00.000Z"
  }
}

Test Webhook

Trigger a test event to verify your endpoint configuration. This sends a mock ping event to your webhook URL.

Endpoint

POST /webhooks/:id/test

Example Request


curl -X POST "https://api.multi-upload-tool.com/api/v1/webhooks/2/test" \
  -H "x-api-key: YOUR_API_TOKEN"

Example Response


{
  "success": true,
  "message": "Test webhook sent successfully"
}

Delete Webhook

Remove a webhook configuration.

Endpoint

DELETE /webhooks/:id

Example Request


curl -X DELETE "https://api.multi-upload-tool.com/api/v1/webhooks/2" \
  -H "x-api-key: YOUR_API_TOKEN"

Example Response


{
  "success": true,
  "message": "Webhook deleted"
}