Payload Structure

The UseStencil Webhook system delivers a fixed JSON payload whenever an image.created event is triggered. The payload contains standardized information about the image, the modifications applied, and any additional context you optionally provide using the user_defined field.

Example payload

{
  "image_url": "https://usestencil.s3.amazonaws.com/dev/images/a3b37b73-6876-44b7-bfd9-dfc3b0ad4157/19da5632-feef-4abd-a28a-e3dfa6077429.png",
  "image_url_jpg": "https://usestencil.s3.amazonaws.com/dev/images/a3b37b73-6876-44b7-bfd9-dfc3b0ad4157/19da5632-feef-4abd-a28a-e3dfa6077429.jpeg",
  "metadata": {},
  "modifications": [
    {
      "name": "image_1",
      "src": "https://usestencil.s3.amazonaws.com/dev/uploads/.../w100_product_highlight_v1.webp"
    },
    {
      "name": "model_name",
      "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit..."
    },
    {
      "name": "text_3",
      "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit..."
    },
    {
      "name": "qrcode_4",
      "value": "https://usestencil.com"
    },
    {
      "name": "barcode_5",
      "value": "1234567890128"
    }
  ],
  "status": "completed",
  "user_defined": {
    "auth": "test"
  }
}

Payload Fields Explained

Field	Type	Description
image_url	string	URL to the final PNG image
image_url_jpg	string	URL to the JPEG version of the image
metadata	object	Metadata from the rendering job (can be empty or enriched in future)
modifications	array	List of template elements and their applied values (text, image, QR, etc.)
status	string	Always completed for now (indicating image generation is done)
user_defined	object	Optional. A dictionary of custom values added by the user when configuring the webhook

User Defined information

The user_defined object allows you to attach custom key-value pairs to every webhook request. You can use this to send:

• A shared secret for verification

• Identifiers like client_id or source

• Any static data your receiving service may need

Example configuration during webhook setup:

{
"auth": "stencil-secret-xyz",
"environment": "staging",
"source": "usestencil"
}

Resulting payload:

"user_defined": {
"auth": "stencil-secret-xyz",
"environment": "staging",
"source": "usestencil"
}

Headers

Webhook requests include standard headers, and optionally custom headers you define:

✅ Next Up: Security & Verification

Learn how to use custom headers and body to protect your webhook endpoints.