> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.templated.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# "Inbound Webhooks: Field Mapping with Dot Notation and Arrays (Tally Example)"

An inbound webhook gives you a unique URL. Any app or form tool that can send a JSON POST (Tally, Typeform, Jotform, your own backend...) can call this URL. Templated maps the incoming data to your template layers and creates a render automatically. No code and no API key are needed in the sending app.

This is different from the Embedded Editor webhooks, which send events from the editor to your server. See "Webhook Integration" for those.

## Create a webhook

1. Go to **Integrations > Webhooks**: https://app.templated.io/integrations/webhooks
2. Click **Create Webhook**.
3. Fill in:
   - **Webhook Name**
   - **Template**: the template to render
   - **Output Format**: jpg, png, pdf...
   - **Callback URL** (optional): Templated POSTs the render result to this URL when it is done.
   - **Active**: on
4. Under **Field Mappings**, click **Add Mapping** for each field:
   - **Incoming Field**: the path to the value in the JSON you will receive.
   - **Layer**: the template layer that receives the value.
   - **Property**: Auto-detect, Text, Image URL, Color, and others. Auto-detect uses `image_url` for values that start with http:// or https://, and `text` for everything else.
5. Save, then click **Copy URL** in the webhooks list and paste the URL in your form tool or app.

The response to the POST contains the render `url`, so tools that read the response can use it directly. Each call uses credits like a normal render.

## Incoming Field: dot notation

Use dots to reach nested values.

Incoming JSON:

```json
{
  "customer": {
    "name": "Maria",
    "photo": "https://example.com/maria.jpg"
  }
}
```

| Incoming Field | Layer | Property |
|---|---|---|
| `customer.name` | `name` | Text |
| `customer.photo` | `photo` | Image URL |

## Incoming Field: arrays

Some tools send the answers as a list. You can reach an item in two ways:

- **By position**: `data.fields.0.value` or `data.fields[0].value` (the first item is `0`).
- **By the item's key or label**: `data.fields.Name.value` finds the item whose `key` or `label` is "Name". The label match ignores uppercase and lowercase.

Using the **label is recommended**. Positions change when you add, remove or reorder questions in your form. Labels keep working.

## Example: Tally

Tally sends a payload like this:

```json
{
  "eventType": "FORM_RESPONSE",
  "data": {
    "fields": [
      { "key": "question_abc", "label": "Full name", "type": "INPUT_TEXT", "value": "Maria Silva" },
      { "key": "question_def", "label": "Course", "type": "INPUT_TEXT", "value": "Design 101" }
    ]
  }
}
```

Mappings for a certificate template:

| Incoming Field | Layer | Property |
|---|---|---|
| `data.fields.Full name.value` | `student-name` | Text |
| `data.fields.Course.value` | `course-name` | Text |

Then in Tally, go to the form's **Integrations > Webhooks** and paste the Templated webhook URL.

## Troubleshooting

**The render is created but shows the template's default text.**
The incoming field path did not find a value. When a path finds nothing, that mapping is skipped and the layer keeps its template value. Check:

- The exact JSON your tool sends (most tools show a sample or a delivery log).
- Each segment of the path, including uppercase and lowercase in object keys.
- For arrays, use the item label or the right position.
- The layer selected in the mapping is the right one.

**The webhook returns an error.**

| Error | Meaning |
|---|---|
| `Webhook not found or invalid secret` (404) | The URL is incomplete or the webhook was deleted or its secret regenerated. Copy the URL again. |
| `Webhook is disabled` (403) | Turn **Active** on. |
| `API quota exceeded` (403) | No credits left. Upgrade your plan. |
| `Payment is past due` (403) | Update your card in Account Settings > Manage Subscription. |
| `Invalid JSON payload` (400) | The sender must POST valid JSON. |

**I regenerated the secret.** The old URL stops working. Paste the new URL in your form tool.

## FAQ

Q: How do I map a field inside an array, like Tally's `data.fields`?
A: Use the label, for example `data.fields.Full name.value`, or the position, for example `data.fields.0.value`. The label is recommended.

Q: Do I need an API key for inbound webhooks?
A: No. The secret in the webhook URL authenticates the request. Keep the URL private.

Q: Where do I get the render URL?
A: It is in the response to the POST, and in the Callback URL payload if you set one. The render is also listed in the Renders page.

Q: Why does my render ignore the form data?
A: The incoming field path does not match the JSON your tool sends. Compare the path with a real sample payload.

Q: Does each webhook call use credits?
A: Yes, the same as a render via API.

Q: Can I set colors or hide layers with a webhook?
A: Yes. Choose the property in the mapping, for example Color or Hide/Show.