Webhooks

Register one or more endpoints and SudoMock sends a signed JSON payload to them when your jobs complete. Webhooks are available on every plan. Polling GET /api/v1/jobs/{job_id} remains the source of truth, and webhooks are a convenience layer on top of it.

Add, edit and rotate endpoints from Dashboard, Webhooks, or through the API. Each endpoint has its own signing secret, prefixed whsec_, shown once when you create or rotate it.

Events

Event	When it fires
`render.succeeded`	An image render job finished successfully.
`render.failed`	An image render job failed.
`upload.succeeded`	A PSD upload finished parsing into a mockup.
`video.succeeded`	A video job finished successfully.
`video.failed`	A video job failed.
`photo_mockup.ready`	A product photo became a reusable photo mockup.
`photo_mockup.rejected`	A product photo was not suitable for a photo mockup.
`photo_mockup.failed`	A photo mockup creation job failed unexpectedly.
`photo_mockup_render.succeeded`	An asynchronous photo mockup render finished successfully.
`photo_mockup_render.failed`	An asynchronous photo mockup render failed.
`webhook.test`	Fired by the test action in the dashboard or by `POST /test`.

Leave event_types empty to subscribe to every event, including ones added later. A failed upload is delivered as render.failed, so subscribe to render.failed if you ingest PSDs.

Endpoints created before the photo_mockup names were introduced are pinned to the earlier spelling of the same five events: 2d_mockup.ready, 2d_mockup.rejected, 2d_mockup.failed, 2d_render.succeeded and 2d_render.failed, with kind spelled 2d_create or 2d_render. They keep receiving them unchanged. The endpoint’s event_naming field reads legacy or current and says which spelling it receives; new endpoints default to current. Either spelling is accepted in event_types. Move an existing endpoint with PATCH { "event_naming": "current" } once your handler reads the new names.

Headers and body

Headers

X-SudoMock-Signature: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
X-SudoMock-Timestamp: 1718900000
Content-Type: application/json

Body

{
  "event": "render.succeeded",
  "job_id": "c315f78f-d2c7-4541-b240-a9372842de94",
  "kind": "render",
  "status": "succeeded",
  "result_url": "https://cdn.sudomock.com/renders/c315f78f.png",
  "error": null,
  "created_at": "2026-06-21T10:00:00Z"
}

Verify the signature before you act on the body. See Verifying signatures.

Create an endpoint

const response = await fetch("https://api.sudomock.com/api/v1/webhook-endpoints", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "sm_your_api_key",
  },
  body: JSON.stringify({
    "url": "https://your-domain.com/hooks/sudomock",
    "description": "Production listener",
    "event_types": []
  }),
});

const data = await response.json();
console.log(data);

<?php

$payload = <<<'JSON'
{
  "url": "https://your-domain.com/hooks/sudomock",
  "description": "Production listener",
  "event_types": []
}
JSON;

$ch = curl_init("https://api.sudomock.com/api/v1/webhook-endpoints");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "x-api-key: sm_your_api_key",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

import requests

payload = {
    "url": "https://your-domain.com/hooks/sudomock",
    "description": "Production listener",
    "event_types": []
}

response = requests.post(
    "https://api.sudomock.com/api/v1/webhook-endpoints",
    headers={"x-api-key": "sm_your_api_key"},
    json=payload,
)

response.raise_for_status()
print(response.json())

require "net/http"
require "uri"

uri = URI("https://api.sudomock.com/api/v1/webhook-endpoints")
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["x-api-key"] = "sm_your_api_key"

request.body = <<~JSON
  {
    "url": "https://your-domain.com/hooks/sudomock",
    "description": "Production listener",
    "event_types": []
  }
JSON

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
  "url": "https://your-domain.com/hooks/sudomock",
  "description": "Production listener",
  "event_types": []
}`)

	req, err := http.NewRequest("POST", "https://api.sudomock.com/api/v1/webhook-endpoints", bytes.NewBuffer(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-api-key", "sm_your_api_key")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String payload = """
{
  "url": "https://your-domain.com/hooks/sudomock",
  "description": "Production listener",
  "event_types": []
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sudomock.com/api/v1/webhook-endpoints"))
    .header("Content-Type", "application/json")
    .header("x-api-key", "sm_your_api_key")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

using System.Net.Http;
using System.Text;

var payload = """
{
  "url": "https://your-domain.com/hooks/sudomock",
  "description": "Production listener",
  "event_types": []
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sudomock.com/api/v1/webhook-endpoints");
request.Headers.Add("x-api-key", "sm_your_api_key");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

var client = new HttpClient();
var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

curl -X POST "https://api.sudomock.com/api/v1/webhook-endpoints" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sm_your_api_key" \
  -d '{
    "url": "https://your-domain.com/hooks/sudomock",
    "description": "Production listener",
    "event_types": []
  }'

The full whsec_ secret is returned only on create and on rotate-secret. Store it when you receive it. Every other read masks it as whsec_****<last4>.

The endpoint object

{
  "id": "we_8f3a...",
  "url": "https://your-domain.com/hooks/sudomock",
  "secret": "whsec_****a1b2",
  "description": "Production listener",
  "event_types": ["render.succeeded", "video.succeeded"],
  "event_naming": "current",
  "enabled": true,
  "created_at": "2026-06-21T10:00:00Z",
  "updated_at": null
}

Deliveries

Every attempt is logged with its HTTP status, attempt count and error.

{
  "id": "wd_2b6f...",
  "endpoint_id": "we_8f3a...",
  "job_id": "c315f78f-d2c7-4541-b240-a9372842de94",
  "event_type": "render.succeeded",
  "status": "pending",
  "http_status": 200,
  "attempt": 1,
  "last_error": null,
  "created_at": "2026-06-21T10:00:01Z",
  "updated_at": null
}

The delivery and events feeds page with an opaque cursor. Make the first request without cursor. When another page exists, the response carries X-Webhook-Next-Cursor. Send that exact value as the next request’s cursor. When the header is absent, the list is complete.

Paging through deliveries

GET /api/v1/webhook-endpoints/events?limit=100
X-Webhook-Next-Cursor: eyJjcmVhdGVkX2F0IjoiMjAyNi0wNy0yNFQxMDowMDowMFoifQ

GET /api/v1/webhook-endpoints/events?limit=100&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wNy0yNFQxMDowMDowMFoifQ

Retries and replay

Failed deliveries are retried automatically. You can inspect every attempt and replay a single delivery, or replay every failed delivery for an endpoint at once. Treat job_id plus the event name as the delivery’s idempotency key, persist it before applying side effects, and return a 2xx response only after processing succeeds. A replayed delivery can arrive with result_url set to null; when that happens, fetch the result by polling GET /api/v1/jobs/{job_id}.

Send a test event

const response = await fetch("https://api.sudomock.com/api/v1/webhook-endpoints/we_8f3a.../test", {
  method: "POST",
  headers: { "x-api-key": "sm_your_api_key" },
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init("https://api.sudomock.com/api/v1/webhook-endpoints/we_8f3a.../test");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: sm_your_api_key",
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

import requests

response = requests.post(
    "https://api.sudomock.com/api/v1/webhook-endpoints/we_8f3a.../test",
    headers={"x-api-key": "sm_your_api_key"},
)

response.raise_for_status()
print(response.json())

require "net/http"
require "uri"

uri = URI("https://api.sudomock.com/api/v1/webhook-endpoints/we_8f3a.../test")
request = Net::HTTP::Post.new(uri)
request["x-api-key"] = "sm_your_api_key"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("POST", "https://api.sudomock.com/api/v1/webhook-endpoints/we_8f3a.../test", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("x-api-key", "sm_your_api_key")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sudomock.com/api/v1/webhook-endpoints/we_8f3a.../test"))
    .header("x-api-key", "sm_your_api_key")
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

using System.Net.Http;
using System.Text;

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sudomock.com/api/v1/webhook-endpoints/we_8f3a.../test");
request.Headers.Add("x-api-key", "sm_your_api_key");

var client = new HttpClient();
var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

curl -X POST "https://api.sudomock.com/api/v1/webhook-endpoints/we_8f3a.../test" \
  -H "x-api-key: sm_your_api_key"

The test event travels the same signed path as a real one, so it exercises your verification code end to end.

Verifying signatures

Check the HMAC before you trust a payload.

Webhook endpoints API

Create, rotate, list, replay and inspect, from your own backend.

Overview

PSD mockups

Photo mockups

Text and fonts

Integrations

Reference

Advanced

Changes

Events

Headers and body

Create an endpoint

The endpoint object

Deliveries

Retries and replay

Send a test event

Verifying signatures

Webhook endpoints API

​Events

​Headers and body

​Create an endpoint

​The endpoint object

​Deliveries

​Retries and replay

​Send a test event

Verifying signatures

Webhook endpoints API

Events

Headers and body

Create an endpoint

The endpoint object

Deliveries

Retries and replay

Send a test event