API Callbacks

WellcomeMat can notify your server when events happen to your media. Callbacks are HTTP GET requests sent to URLs you provide, with event data passed as query parameters.

There are four callback types, each triggered at a different stage of the media lifecycle:

Setting Up Callbacks

Per-upload callbacks

Pass callback_uploaded and/or callback_location as query parameters when uploading via the API. The Toolset supports callback_location only.

https://www.wellcomemat.com/embed/uploader?key=<KEY>&secret=<SECRET>&callback_location=https://example.com/wm/location

Per-media callbacks

callback_processed and callback_changed are stored on the media record. Set them via the Media API when creating or updating a media item.

callback_uploaded

Triggered when a media upload completes or fails. Delivered as a browser redirect (HTTP 302), so this callback only works when the upload happens in a browser context.

Success

GET https://example.com/wm/uploaded?success=1&hash=a1b2c3d4e5f6&error=&key=yourApiKey

Error

GET https://example.com/wm/uploaded?success=0&hash=&error=No+file+was+uploaded

Note: The key parameter is not included in error callbacks.

callback_location

Triggered when a media upload completes or fails. Delivered as a server-to-server GET request, so your server receives it regardless of browser context.

On success, the full media object is included as a JSON-encoded media query parameter. Because the full media payload is URL-encoded in the query string, the resulting URL can be long. Ensure your server and any intermediary proxies or load balancers accept URLs of at least 8,000 characters.

Success

GET https://example.com/wm/location?success=1&key=yourApiKey&error=&media=%7B...%7D

Success media payload example

The media parameter is a URL-encoded JSON string. When decoded, it contains the full media object:

{
  "media_id": 123456,
  "hash": "a1b2c3d4e5f6",
  "isDefaultForListing": true,
  "created": "2026-05-06 14:30:00",
  "replaced": null,
  "data_updated": "2026-05-06 14:30:00",
  "status_code": "queued_for_encoding",
  "status_message": "Queued For Encoding",
  "status_group": "processing",
  "is_ready": false,
  "user_id": 789,
  "title": "123 Main Street Virtual Tour",
  "keywords": "real estate, virtual tour, Denver",
  "customid": "MLS-12345678",
  "original_file": "123-main-street.mp4",
  "original_size_bytes": 157286400,
  "original_size_readable": "150.00 MB",
  "source": "toolset",
  "traffic_url": "https://example.com/listing/MLS-12345678",
  "slideshow": 0,
  "video_type": 1,
  "price": 450000,
  "location": {
    "address": "123 Main Street",
    "city": "Denver",
    "state_province": "CO",
    "postal_code": "80202",
    "latitude": "39.7392",
    "longitude": "-104.9903"
  },
  "video": null,
  "preview": null,
  "image": null,
  "photos": {
    "https_url": "https://f9d1f107e6c5b1517a51-aaf17496434b6d0932e6009b64e8d8e3.ssl.cf1.rackcdn.com",
    "seconds": {}
  },
  "links": {
    "base": "https://www.wellcomemat.com/video/a1b2c3d4e5f6",
    "embed": "https://www.wellcomemat.com/embed/a1b2c3d4e5f6",
    "share": "https://www.wellcomemat.com/s/a1b2c3d4e5f6",
    "unbranded_base": "https://www.wellcomemat.com/mls/a1b2c3d4e5f6",
    "unbranded_embed": "https://www.wellcomemat.com/embed/a1b2c3d4e5f6?mls=1"
  }
}

After encoding completes, fields like video, preview, image, photos.seconds, is_ready, and status_code will be populated. At upload time, encoding has not started yet, so video-related fields are null.

Note: The callback payload is built by a separate code path from the Media API response. Some fields differ in type or format - for example, status_code uses descriptive strings (e.g. "queued_for_encoding") rather than numeric codes, and numeric fields like user_id, slideshow, and video_type are returned as numbers rather than strings. Do not assume callback payloads match the Media API response schema.

Error

GET https://example.com/wm/location?success=0&hash=&error=No+file+was+uploaded

Note: The key and media parameters are not included in error callbacks.

callback_processed

Triggered when encoding completes (successfully or with an error). Delivered as a server-to-server GET request.

Example

GET https://example.com/wm/processed?hash=a1b2c3d4e5f6&status=Completed

Status values

callback_changed

Triggered when a tracked property on a media record changes. Delivered as a server-to-server GET request.

This callback is delta-only: it includes the media hash for identification plus only the fields that changed. It does not send the full media payload.

Example

GET https://example.com/wm/changed?hash=a1b2c3d4e5f6&isDefaultForListing=true

Currently, isDefaultForListing is the only field sent via callback_changed. Additional fields may be added in the future, but callback_changed will always be delta-only (only changed fields, never a full payload).

Notes

• All callbacks are sent as HTTP GET requests with data in query parameters.
• For server-to-server callbacks (callback_location, callback_processed, callback_changed), your endpoint should return an HTTP 2xx status code to acknowledge receipt. Non-2xx responses are logged as errors on our side, but callbacks are not retried. This does not apply to callback_uploaded, which is a browser redirect - WellcomeMat does not observe your endpoint’s response in that case.
• callback_uploaded is a browser redirect and is only useful when the upload happens in a browser. For server-to-server notifications, use callback_location instead.
• To verify that callback requests originate from WellcomeMat, contact support for our current server IP ranges. The key parameter included on success callbacks is your API key (not a secret), so it should not be used as the sole means of authentication.