# 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

{% code lineNumbers="true" %}

```json
{
  "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"
  }
}
```

{% endcode %}

## Payload Fields Explained

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

### 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](https://docs.usestencil.com/integrations/webhook-integration/security-and-verification)
>
> Learn how to use custom headers and body to protect your webhook endpoints.