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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.usestencil.com/integrations/webhook-integration/payload-structure.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.