Sandbox environment

Test your integration safely using a sandbox API key

Overview

The sandbox lets you exercise your integration without running real asset processing or consuming processing credits. It is not a separate host or base URL. You select the sandbox by using a sandbox API key: the same base URL and the same paths behave as a sandbox when the request is authenticated with an sk_test_ key.

Sandbox keys unlock two capabilities:

• A simulationDelaySeconds query parameter on submission creation, to control timing.
• A POST /api/integrations/sandbox/events/fire endpoint, to dispatch synthetic webhook events to your subscriptions without real processing.

Using a sandbox key

Use your sk_test_ key against the normal base URL and the normal endpoints.

curl -X POST https://mm-midmarket-integrations-api-preview.azurewebsites.net/api/integrations/submissions \
  -H "X-API-Key: sk_test_your_sandbox_key" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      { "blobPath": "<workspace-id>/test.mp4" }
    ]
  }'

A live (sk_live_) key calls the same endpoints but cannot use the sandbox-only features described below.

Simulating processing time

Add the simulationDelaySeconds query parameter to a submission-create request to delay when the submission reaches a terminal state. This is useful for exercising your polling and webhook-handling logic.

curl -X POST "https://mm-midmarket-integrations-api-preview.azurewebsites.net/api/integrations/submissions?simulationDelaySeconds=5" \
  -H "X-API-Key: sk_test_your_sandbox_key" \
  -H "Content-Type: application/json" \
  -d '{ "assets": [ { "blobPath": "<workspace-id>/test.mp4" } ] }'

• The parameter is camelCase: simulationDelaySeconds.
• Accepted range is 0 to 30 seconds. Default is 0.
• It works only with a sandbox key. Sending it on a live key returns a 400.

Firing synthetic webhook events

To test your webhook handler end to end, fire a synthetic event for an existing submission’s assets. The endpoint dispatches the event to every matching subscription in your workspace, exactly as a real processing event would, but without running any processing.

POST /api/integrations/sandbox/events/fire

Request body (camelCase):

{
  "eventType": "asset.processing.failed",
  "submissionId": "550e8400-e29b-41d4-a716-446655440000",
  "errorMessage": "Simulated processing failure"
}

Field	Required	Notes
eventType	Yes	One of asset.processing.completed or asset.processing.failed
submissionId	Yes	A submission that exists in your workspace
errorMessage	No	Optional message, used with asset.processing.failed

Response 200:

{
  "dispatched": 2
}

dispatched is the number of subscriptions notified across all of the submission’s assets.

This endpoint is sandbox-only. Behaviour by condition:

Condition	Result
Sandbox key, submission in workspace	200 with dispatched count
Live key	403
submissionId not found in your workspace	404
Malformed request body	422

Testing the failure path

To verify your handler reacts correctly to failures, subscribe a webhook, create a submission, then fire an asset.processing.failed event and confirm your endpoint received it. This replaces any approach that inspects mocked inline results — the sandbox does not return mocked processing output.

import requests

API_BASE = "https://mm-midmarket-integrations-api-preview.azurewebsites.net"
api_key = "sk_test_your_sandbox_key"


def test_failure_webhook(submission_id: str) -> None:
    """Subscribe, fire a synthetic failure event, and confirm dispatch."""
    # 1. Subscribe to the failure event.
    sub = requests.post(
        f"{API_BASE}/api/integrations/webhooks/subscriptions",
        headers={"X-API-Key": api_key},
        json={
            "endpointUrl": "https://your-domain.com/webhooks/test",
            "eventTypes": ["asset.processing.failed"],
            "description": "Sandbox failure test",
        },
    )
    secret = sub.json()["secret"]
    print(f"Subscribed; verify deliveries with secret {secret}")

    # 2. Fire a synthetic failure for an existing submission's assets.
    fired = requests.post(
        f"{API_BASE}/api/integrations/sandbox/events/fire",
        headers={"X-API-Key": api_key},
        json={
            "eventType": "asset.processing.failed",
            "submissionId": submission_id,
            "errorMessage": "Simulated processing failure",
        },
    )

    dispatched = fired.json()["dispatched"]
    assert dispatched >= 1, "expected at least one subscription to be notified"
    print(f"Dispatched failure event to {dispatched} subscription(s)")
    print("Now assert your endpoint received an asset.processing.failed event")

The delivered webhook payload follows the standard shape documented in Webhook subscriptions: an outer type of asset.processing.failed, with a snake_case data object containing asset_id, submission_id, workspace_id, status of "failed", and error_message.

Key differences from production

Aspect	Sandbox (sk_test_ key)	Production (sk_live_ key)
Selection	API key prefix sk_test_	API key prefix sk_live_
Base URL and paths	Same as production	Same as sandbox
Processing	None when using the fire endpoint; no real credits consumed	Real processing
Webhook events	Can be fired synthetically via /sandbox/events/fire	Emitted by real processing
Timing control	simulationDelaySeconds (0–30) on submission create	Not available

Best practices

• Use a sandbox key for all integration testing before switching to a live key.
• Exercise your failure handling by firing asset.processing.failed, not by inspecting mocked results.
• Use simulationDelaySeconds to test polling and webhook timing.
• Verify webhook signature handling against the secret returned when you create a subscription.

Troubleshooting

Webhook not delivered

• Ensure your endpoint is publicly reachable and returns 200
• Confirm the subscription’s eventTypes includes the event you fired
• Check that dispatched was at least 1 in the fire response
• Review delivery history via the subscription’s deliveries endpoint

simulationDelaySeconds rejected

• The parameter is camelCase: simulationDelaySeconds
• The value must be between 0 and 30
• A 400 means it was sent on a live key — use a sandbox (sk_test_) key

Fire endpoint returns 403 or 404

• 403 means you used a live key; sandbox events require a sk_test_ key
• 404 means the submissionId does not exist in your workspace

Ready for production?

Switch to your live (sk_live_) key against the same endpoints. Create or manage keys in the control plane, or contact support at https://support.mediamagic.app.