Receive Real-Time Webhook Events from the UMW Platform

Webhooks let your application react to events on the UMW platform the moment they happen, without polling the API. When a release is delivered to stores, a statement is generated, or a payout is processed, UMW sends an HTTP POST request containing a structured event payload to an endpoint you register. This guide walks you through registering an endpoint, verifying authenticity, handling the event envelope, and building resilient event consumers.

Setting Up Webhooks

Register the URL where UMW should send events. You can subscribe to specific event types to limit noise to only the signals relevant to your integration.

POST /v1/webhooks

{
  "url": "https://app.yourdomain.com/webhooks/umw",
  "description": "Production event handler for catalog and payout workflows",
  "events": [
    "release.status.changed",
    "delivery.completed",
    "statement.generated",
    "payout.completed"
  ],
  "active": true
}

Response:

{
  "id": "whk_01HXKF6QR7STUV8WXYZ9ABC0D",
  "url": "https://app.yourdomain.com/webhooks/umw",
  "description": "Production event handler for catalog and payout workflows",
  "events": [
    "release.status.changed",
    "delivery.completed",
    "statement.generated",
    "payout.completed"
  ],
  "active": true,
  "secret": "whsec_4f8a2b1c9d3e7f6a0b5c2d1e8f3a9b4c",
  "created_at": "2024-06-15T13:00:00Z"
}

The secret field is returned only once at registration time. Store it securely in your secrets manager immediately — you will use it to verify the signature of every incoming event. If you lose the secret, you must rotate it via POST /v1/webhooks/{webhook_id}/rotate-secret.

Verify Your Endpoint

After you register, UMW sends a one-time ping event to your endpoint to confirm it is reachable. Your server must respond with an HTTP 200 status code within 10 seconds.Ping event payload:

{
  "id": "evt_01HXKG7RS8TUVW9XYZ0ABCD1E",
  "type": "ping",
  "created_at": "2024-06-15T13:00:05Z",
  "data": {
    "webhook_id": "whk_01HXKF6QR7STUV8WXYZ9ABC0D",
    "message": "Endpoint verification ping from UMW. Respond with 200 to confirm."
  }
}

If your endpoint does not respond with 200 within the timeout window, the webhook will be created in an unverified state and no live events will be delivered until verification succeeds. You can trigger a new ping at any time:

POST /v1/webhooks/{webhook_id}/ping

Handle Incoming Events

All UMW events share a consistent envelope structure. Parse the outer fields first to identify the event type, then route the data object to your domain-specific handler.Event envelope:

Field	Type	Description
`id`	string	Globally unique event identifier. Use this for deduplication.
`type`	string	Dot-notated event type (e.g., `release.status.changed`)
`created_at`	string	ISO 8601 timestamp when the event was generated on the UMW platform
`data`	object	Event-specific payload. Schema varies by `type`.

Example — release.status.changed event:

{
  "id": "evt_01HXK9P2ZQMB4NVYJR3T5C8WD",
  "type": "release.status.changed",
  "created_at": "2024-06-15T14:22:00Z",
  "data": {
    "release_id": "rel_01HXK3AB7NMCPQ2XYZ9WD4EF5",
    "previous_status": "submitted",
    "status": "delivered"
  }
}

Your handler should return an HTTP 200 response as quickly as possible — ideally before performing any heavy business logic. Enqueue events for asynchronous processing to avoid timeouts that would cause UMW to retry delivery unnecessarily.

Verify the Signature

Every event UMW delivers includes an X-UMW-Signature header. Validate this signature before processing the event to confirm it originated from UMW and was not tampered with in transit.The signature is computed as an HMAC-SHA256 digest of the raw request body, using your webhook secret as the key. The header value is prefixed with sha256=.

X-UMW-Signature: sha256=a4f2c8b1e3d9f07a65c2b4e1d8f3a9b4c2e7f6a0b5c1d2e8f3a9b4c2e7f6a0b5

import hmac
import hashlib
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_4f8a2b1c9d3e7f6a0b5c2d1e8f3a9b4c"

@app.route("/webhooks/umw", methods=["POST"])
def handle_umw_webhook():
    signature_header = request.headers.get("X-UMW-Signature", "")
    raw_body = request.get_data()

    expected_sig = "sha256=" + hmac.new(
        WEBHOOK_SECRET.encode("utf-8"),
        raw_body,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected_sig, signature_header):
        abort(401, "Invalid signature")

    event = request.get_json()
    event_type = event.get("type")

    if event_type == "release.status.changed":
        handle_release_status_changed(event["data"])
    elif event_type == "delivery.completed":
        handle_delivery_completed(event["data"])
    elif event_type == "statement.generated":
        handle_statement_generated(event["data"])
    elif event_type == "payout.completed":
        handle_payout_completed(event["data"])

    return "", 200

import express from "express";
import crypto from "crypto";

const app = express();
const WEBHOOK_SECRET = "whsec_4f8a2b1c9d3e7f6a0b5c2d1e8f3a9b4c";

// Parse raw body for signature verification
app.use("/webhooks/umw", express.raw({ type: "application/json" }));

app.post("/webhooks/umw", (req, res) => {
  const signatureHeader = req.headers["x-umw-signature"] ?? "";
  const rawBody = req.body;

  const expectedSig =
    "sha256=" +
    crypto
      .createHmac("sha256", WEBHOOK_SECRET)
      .update(rawBody)
      .digest("hex");

  const isValid = crypto.timingSafeEqual(
    Buffer.from(expectedSig, "utf8"),
    Buffer.from(signatureHeader, "utf8")
  );

  if (!isValid) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const event = JSON.parse(rawBody);

  switch (event.type) {
    case "release.status.changed":
      handleReleaseStatusChanged(event.data);
      break;
    case "delivery.completed":
      handleDeliveryCompleted(event.data);
      break;
    case "statement.generated":
      handleStatementGenerated(event.data);
      break;
    case "payout.completed":
      handlePayoutCompleted(event.data);
      break;
  }

  res.status(200).send();
});

Always use a constant-time comparison function (hmac.compare_digest in Python, crypto.timingSafeEqual in Node.js) when comparing signatures. Standard string equality is vulnerable to timing attacks.

Retry Logic

If your endpoint returns a non-2xx status code, or does not respond within the 30-second timeout window, UMW will automatically retry delivery with exponential backoff.

Attempt	Delay After Previous Attempt
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	8 hours

After 5 failed retries, the event is marked as undeliverable and no further attempts are made. You can view all undelivered events and trigger manual redelivery from the UMW developer dashboard or via the API:

GET /v1/webhooks/{webhook_id}/events?status=failed

POST /v1/webhooks/{webhook_id}/events/{event_id}/redeliver

UMW retains event history for 30 days. If your endpoint experiences a prolonged outage, use the relevant REST endpoints (e.g., GET /v1/deliveries, GET /v1/royalties) to backfill any state you may have missed from failed webhook deliveries.

Deduplication

UMW guarantees at-least-once delivery — under certain network or infrastructure conditions, your endpoint may receive the same event more than once. Design your event handlers to be idempotent by tracking the id field of each processed event.

def handle_umw_webhook(event):
    event_id = event["id"]

    # Check if this event has already been processed
    if already_processed(event_id):
        return  # Silently acknowledge the duplicate

    process_event(event)
    mark_as_processed(event_id)

A Redis SET NX operation, a unique constraint on a database events table, or any idempotency key store with a TTL of at least 30 days is sufficient for deduplication.

Supported Events

Event Type	Trigger
`release.status.changed`	A release transitions to a new status (e.g., `validating`, `ready`, `delivered`, `action_required`)
`delivery.completed`	A delivery order is confirmed live on all requested stores (`delivered` state)
`delivery.rejected`	One or more stores reject the delivery; inspect per-store `rejection_reason` for details
`statement.generated`	A new royalty statement has been generated and is available for your account
`payout.completed`	A payout has been successfully processed and transferred to your registered payout account
`payout.failed`	A payout could not be processed; check the payout record for the failure reason and next steps
`ping`	A one-time verification ping sent when a new webhook endpoint is registered
`asset.processing.failed`	An uploaded asset failed format or quality validation; see `validation_errors` in the event data
`takedown.completed`	A takedown request has been confirmed by all targeted stores

Get Started

Platform Guides

Platform Reference

Receive Real-Time Webhook Events from the UMW Platform

Setting Up Webhooks

Retry Logic

Deduplication

Supported Events

​Setting Up Webhooks

​Retry Logic

​Deduplication

​Supported Events

Setting Up Webhooks

Retry Logic

Deduplication

Supported Events