Create a webhook

Example

curl "https://api.switchfile.io/v2/webhooks" \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/switchfile",
    "events": [
      "job.finished",
      "job.failed"
    ]
  }'

const res = await fetch("https://api.switchfile.io/v2/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SWITCHFILE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/hooks/switchfile",
    events: [
      "job.finished",
      "job.failed"
    ]
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
console.log(await res.json());

<?php
$ch = curl_init('https://api.switchfile.io/v2/webhooks');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://example.com/hooks/switchfile',
        'events' => [
            'job.finished',
            'job.failed',
        ],
    ]),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SWITCHFILE_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new RuntimeException("HTTP $status: $response");
}
print_r(json_decode($response, true));

import os
import requests

res = requests.post(
    "https://api.switchfile.io/v2/webhooks",
    headers={"Authorization": f"Bearer {os.environ['SWITCHFILE_API_KEY']}"},
    json={
        "url": "https://example.com/hooks/switchfile",
        "events": [
            "job.finished",
            "job.failed",
        ],
    },
)
res.raise_for_status()
print(res.json())

Request body

Responses

• 201Created

  • dataCreatedWebhookrequired
  • data.created_atstringrequired

    ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00

  • data.disabledbooleanrequired

    Always false: switchfile does not disable webhooks on its own

  • data.eventsstring[]required
  • data.failingbooleanrequired

    The last delivery to this URL failed

  • data.idstringrequired

    ID of the webhook (a UUID; CloudConvert uses an integer)

  • data.last_error_atstring | nullrequired

    ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00

  • data.last_response_codestring | nullrequired

    HTTP status of the last failed delivery, or NETWORK_ERROR

  • data.linksobjectrequired
  • data.links.selfstringrequired
  • data.signing_secretstringrequired

    Signing secret of the account. Only in this response

  • data.updated_atstringrequired

    ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00

  • data.urlstringrequired

  201 application/jsonCopy

  {
    "data": {
      "id": "1a7e3c5b-9d2f-4b6a-8e0c-5f3d1b7a9c24",
      "url": "https://example.com/hooks/switchfile",
      "disabled": false,
      "events": [
        "job.finished",
        "job.failed"
      ],
      "failing": false,
      "last_error_at": null,
      "last_response_code": null,
      "created_at": "2026-11-06T18:00:00+00:00",
      "updated_at": "2026-11-06T18:00:00+00:00",
      "links": {
        "self": "https://api.switchfile.io/v2/webhooks/1a7e3c5b-9d2f-4b6a-8e0c-5f3d1b7a9c24"
      },
      "signing_secret": "your-signing-secret"
    }
  }

• 401The API key is missing or not validUNAUTHENTICATED

  401 application/jsonCopy

  {
    "message": "Missing or invalid API key.",
    "code": "UNAUTHENTICATED"
  }

• 404Does not exist for this accountNOT_FOUND

  404 application/jsonCopy

  {
    "message": "Job not found.",
    "code": "NOT_FOUND"
  }

• 409The account has a webhook already. Delete it first or change it in the dashboardWEBHOOK_EXISTS

  409 application/jsonCopy

  {
    "message": "This account already has a webhook. switchfile has one webhook per account: delete it first or change it in the dashboard.",
    "code": "WEBHOOK_EXISTS"
  }

• 411The request has a body but no Content-Length headerLENGTH_REQUIRED

  411 application/jsonCopy

  {
    "message": "A Content-Length header is required for this request.",
    "code": "LENGTH_REQUIRED"
  }

• 413The request or the file is too largePAYLOAD_TOO_LARGE

  413 application/jsonCopy

  {
    "message": "The request body is larger than the allowed maximum.",
    "code": "PAYLOAD_TOO_LARGE"
  }

• 422The URL is not a public http or https address, or an event is unknownINVALID_DATA

  422 application/jsonCopy

  {
    "message": "url: The URL points to a private, reserved or own network address.",
    "code": "INVALID_DATA",
    "errors": {
      "url": [
        "The URL points to a private, reserved or own network address."
      ]
    }
  }

• 429Too many requests or a daily quota is used up. See Retry-AfterRATE_LIMIT_EXCEEDED

  429 application/jsonCopy

  {
    "message": "Too many requests. Try again in 12 seconds.",
    "code": "RATE_LIMIT_EXCEEDED"
  }

Error bodies and codes are explained in Errors.