snapcasterDevelopers

    API reference · Webhooks

    Send a test event to your webhook endpoint

    POST /webhooks/test

    Queues one signed webhook.test event to your platform's registered webhook endpoint, so you can check that your receiver accepts deliveries and verifies their signature. It is signed and retried exactly like a real event, works for every subscription and in every environment, and changes nothing: no order, no stock. Retrying with the same Idempotency-Key returns the same event_id and sends nothing more. A platform may send 5 test events every 60 seconds.

    Example

    These examples send requests to the sandbox.

    Generated cURL request - Sandbox
    curl --request POST \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/webhooks/test' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY" \
  --header "Idempotency-Key: $(uuidgen)"

    $(uuidgen) makes a new Idempotency-Key each time you run the command. To retry a command after a lost response, send the key from the first attempt.

    Response 202: Queued test event
    {
  "success": true,
  "data": {
    "event_id": "evt_5b0e7c2d9a4f41e8b3c6d1a07f2e9b58"
  }
}

    Endpoint

    EnvironmentURL
    Sandboxhttps://api-sandbox.snapcaster.ca/api/v1/marketplace/webhooks/test
    Productionhttps://api.snapcaster.ca/api/v1/marketplace/webhooks/test
    Authentication
    • marketplaceApiKey - http bearer. Send the seller's marketplace API key as Authorization: Bearer mp_{sellerCode}_{hex}. The mp_{sellerCode}_ prefix identifies the seller; the trailing hex is the secret. The seller generates the key and supplies it to your platform.

    Request

    Headers

    Idempotency-Key string required

    Keep this UUID when retrying the same order operation and body. Keys remain valid for the lifetime of the order. Changed contents return 409 IDEMPOTENCY_CONFLICT; a concurrent attempt returns 409 REQUEST_IN_PROGRESS with Retry-After.

    Constraints: format: uuid Example f04e4a96-3c99-44dc-abce-5b6862c589c9

    X-Snapcaster-Api-Version string

    Override the platform pin for this request only. Webhook versions and the platform pin do not change.

    Constraints: allowed values: 2026-10 Example 2026-10

    Response

    202

    The test event is queued for your endpoint.

    Response body: WebhookTestResponse

    success boolean required

    Whether the operation completed as requested.

    Constraints: allowed values: true Example true

    data object required

    The operation or event payload.

    Show child fieldsHide child fields
    data.event_id string required

    The event_id the webhook.test delivery carries. The same key returns the same id (STABLE).

    Example evt_5b0e7c2d9a4f41e8b3c6d1a07f2e9b58

    Errors

    Errors return a MarketplaceError body, except HTTP 500 (ApiError). Error codes explains both error bodies and lists every code.

    • 400 INVALID_REQUEST IDEMPOTENCY_KEY_REQUIRED UNSUPPORTED_API_VERSION

      Invalid command body or missing/invalid UUID Idempotency-Key. Unknown or retired API-version override (UNSUPPORTED_API_VERSION).

      Do this: Correct the request fields and supply a UUID Idempotency-Key. Keep the same key when retrying the same command. For UNSUPPORTED_API_VERSION, choose a supported version from the API versioning guide.

    • 401 UNAUTHORIZED

      Missing or invalid marketplace API key (UNAUTHORIZED).

      Do this: Send the marketplace API key for this seller as a Bearer token, then retry.

    • 409 WEBHOOK_ENDPOINT_NOT_REGISTERED

      Your platform has no webhook endpoint registered, so there is nowhere to send the test.

      Do this: Ask Snapcaster to register your receiver URL and signing secret for this environment, then retry.

    • 429 RATE_LIMITED

      More than 5 test events in the last 60 seconds for this platform (RATE_LIMITED).

      Do this: Wait the Retry-After duration in seconds, then retry.

    • 500 INTERNAL_ERROR

      An unexpected failure (INTERNAL_ERROR).

      Do this: Retry with bounded retries and jitter. If the failure persists, contact Snapcaster with the X-Correlation-ID response header.