For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dashboard
GuidesIntegrationsAPI ReferencesRelease notes
GuidesIntegrationsAPI ReferencesRelease notes
    • APIs overview
  • Upload API
    • Errors
  • REST API
    • Authentication
    • File Metadata
    • Add Ons
      • GETList of webhooks
      • POSTCreate webhook
      • PUTUpdate webhook
      • DELDelete webhook
    • Changelog
    • Versioning
  • URL API
    • File Information
    • File Names
    • File groups
    • Image processing limitations
    • Image compression
    • Image resize and crop
    • Image rotation
    • Image overlays
    • Image colors
    • Image definition
    • Image recognition
    • Other image operations
    • Proxy
    • Signed URLs
    • CDN settings
    • Integrations
Dashboard
LogoLogo
REST APIWebhook

Create webhook

POST
https://api.uploadcare.com/webhooks/
POST
/webhooks/
$curl -X POST https://api.uploadcare.com/webhooks/ \
>     -H "Accept: application/vnd.uploadcare-v0.7+json" \
>     -H "Authorization: <apiKey>" \
>     -H "Content-Type: application/x-www-form-urlencoded" \
>     -d "target_url=http%3A%2F%2Fexample.com%2Fhooks%2Freceiver" \
>     -d "event=file.uploaded"
1{
2  "id": 1,
3  "project": 13,
4  "created": "2016-04-27T11:49:54.948615Z",
5  "updated": "2016-04-27T12:04:57.819933Z",
6  "event": "file.infected",
7  "target_url": "http://example.com/hooks/receiver",
8  "is_active": true,
9  "version": "0.7",
10  "signing_secret": "7kMVZivndx0ErgvhRKAr"
11}
Create and subscribe to a webhook. You can use webhooks to receive notifications about your uploads. For instance, once a file gets uploaded to your project, we can notify you by sending a message to a target URL.
Was this page helpful?
Previous

Update webhook

Next
Built with

Authentication

Authorizationstring
Every request made to `https://api.uploadcare.com/` MUST be signed. HTTPS SHOULD be used with any authorization scheme. Requests MUST contain the `Authorization` header defining `auth-scheme` and `auth-param`: `Authorization: auth-scheme auth-param`. Every request MUST contain the `Accept` header identifying the REST API version: `Accept: application/vnd.uploadcare-v0.7+json`. There are two available authorization schemes: * For production: `Uploadcare`, a scheme where a `signature`, not your Secret API Key MUST be specified. Signatures SHOULD be generated on backend. * For quick tests: `Uploadcare.Simple`, a simple scheme where your [Secret API Key](https://app.uploadcare.com/projects/-/api-keys/) MUST be specified in every request's `auth-param`.

Headers

AcceptstringRequired
Version header.

Request

This endpoint expects an object.
target_urlstringRequiredformat: "uri"<=255 characters

A URL that is triggered by an event, for example, a file upload. A target URL MUST be unique for each project — event type combination.

eventenumRequired
An event you subscribe to.
Allowed values:
is_activebooleanOptionalDefaults to true

Marks a subscription as either active or not, defaults to true, otherwise false.

signing_secretstringOptionalformat: "password"<=32 characters
Optional [HMAC/SHA-256](https://en.wikipedia.org/wiki/HMAC) secret that, if set, will be used to calculate signatures for the webhook payloads sent to the `target_url`. Calculated signature will be sent to the `target_url` as a value of the `X-Uc-Signature` HTTP header. The header will have the following format: `X-Uc-Signature: v1=<HMAC-SHA256-HEX-DIGEST>`. See [Secure Webhooks](https://uploadcare.com/docs/webhooks/#signed-webhooks) for details.
versionenumOptionalDefaults to 0.7
Webhook payload's version.
Allowed values:

Response

Webhook successfully created.
idinteger
Webhook's ID.
projectinteger
Project ID the webhook belongs to.
createddatetime

date-time when a webhook was created.

updateddatetime

date-time when a webhook was updated.

eventenum
An event you subscribe to.
Allowed values:
target_urlstringformat: "uri"<=255 characters

A URL that is triggered by an event, for example, a file upload. A target URL MUST be unique for each project — event type combination.

is_activebooleanDefaults to true

Marks a subscription as either active or not, defaults to true, otherwise false.

versionenum
Webhook payload's version.
Allowed values:
signing_secretstringformat: "password"<=32 characters

Optional HMAC/SHA-256 secret that, if set, will be used to calculate signatures for the webhook payloads sent to the target_url.

Calculated signature will be sent to the target_url as a value of the X-Uc-Signature HTTP header. The header will have the following format: X-Uc-Signature: v1=<HMAC-SHA256-HEX-DIGEST>. See Secure Webhooks for details.

Errors

400
Bad Request Error
401
Unauthorized Error
406
Not Acceptable Error
429
Too Many Requests Error

Every request made to https://api.uploadcare.com/ MUST be signed. HTTPS SHOULD be used with any authorization scheme.

Requests MUST contain the Authorization header defining auth-scheme and auth-param: Authorization: auth-scheme auth-param.

Every request MUST contain the Accept header identifying the REST API version: Accept: application/vnd.uploadcare-v0.7+json.

There are two available authorization schemes:

  • For production: Uploadcare, a scheme where a signature, not your Secret API Key MUST be specified. Signatures SHOULD be generated on backend.
  • For quick tests: Uploadcare.Simple, a simple scheme where your Secret API Key MUST be specified in every request’s auth-param.

Optional HMAC/SHA-256 secret that, if set, will be used to calculate signatures for the webhook payloads sent to the target_url.

Calculated signature will be sent to the target_url as a value of the X-Uc-Signature HTTP header. The header will have the following format: X-Uc-Signature: v1=<HMAC-SHA256-HEX-DIGEST>. See Secure Webhooks for details.