# Webhook Destination Field and Payload Mappers

### Overview

The **Webhook Destination** in Ascent allows you to customize the structure of webhook payloads before they are sent to your external systems.\
Two optional configuration parameters are available:

* **`field_mapper`** - remaps or restructures fields inside the webhook payload
* **`payload_mapper`** - wraps the entire payload under a custom root field

These options provide flexibility for integrating alerts with third-party systems that expect a specific JSON schema.

***

### Configuration

#### JSON Schema

```json
{
  "url": "https://your-webhook-endpoint.com/webhook",
  "username": "optional_username",
  "password": "optional_password",
  "field_mapper": "source_field:destination_field,nested.field:nested.destination",
  "payload_mapper": "optional_wrapper_field"
}
```

#### Default Payload (No Mappers)

If no mappers are configured, webhook payloads have this default structure:

```json
{
  "event": "alert_state_change",
  "alert": {
    "id": 123,
    "name": "Alert Name",
    "state": "triggered",
    "severity": "info",
    "rows": [
      { "column1": "value1", "column2": "value2" }
    ]
  },
  "url_base": "https://your-apica-instance.com"
}
```

***

### Field Mapper

#### Purpose

The **`field_mapper`** parameter allows renaming or restructuring fields in the payload to match the format expected by the receiving system.\
It supports dot notation for nested fields and multiple mappings separated by commas.

#### Syntax

```
field_mapper: "source_field:destination_field"
```

**Examples of dot notation:**

* `alert.name:title` → moves `alert.name` → `title`
* `event:meta.type` → moves flat field `event` → nested `meta.type`
* `alert.severity:notification.level` → nested → nested mapping

#### Examples

**1. Simple field renaming**

```
field_mapper: "event:type,url_base:apica_url"
```

**Result:**

```json
{
  "type": "alert_state_change",
  "alert": {...},
  "apica_url": "https://..."
}
```

**2. Extract nested fields**

```
field_mapper: "alert.name:alert_name,alert.severity:severity_level"
```

**Result:**

```json
{
  "alert_name": "Alert Name",
  "severity_level": "high",
  "alert": {...},
  "url_base": "https://..."
}
```

**3. Create nested destinations**

```
field_mapper: "alert.name:notification.title,alert.severity:meta.level,event:meta.event_type"
```

**Result:**

```json
{
  "notification": { "title": "Database Alert" },
  "meta": { "level": "critical", "event_type": "alert_state_change" },
  "alert": {...}
}
```

**4. Mixed levels**

```
field_mapper: "event:notification_type,alert:data,alert.id:alert_id"
```

**Result:**

```json
{
  "notification_type": "alert_state_change",
  "data": {...},
  "alert_id": 123
}
```

#### Behavior Notes

* Dot notation supported for both source and destination.
* Whitespace around names is trimmed.
* Missing fields log warnings but don’t interrupt execution.
* Mapped fields are **moved**, not duplicated.
* Intermediate objects are auto-created for nested destinations.
* Type safety: existing non-object paths are not overwritten.

***

### Payload Mapper

#### Purpose

The **`payload_mapper`** wraps the entire webhook payload inside a single field.\
Useful for APIs that require a top-level object or “envelope.”

#### Syntax

```
payload_mapper: "wrapper_field_name"
```

#### Examples

**1. Basic wrapping**

```
payload_mapper: "data"
```

**Result:**

```json
{
  "data": {
    "event": "alert_state_change",
    "alert": {...},
    "url_base": "https://..."
  }
}
```

**2. Custom wrapper**

```
payload_mapper: "apica_notification"
```

**Result:**

```json
{
  "apica_notification": {
    "event": "alert_state_change",
    "alert": {...},
    "url_base": "https://..."
  }
}
```

#### Behavior Notes

* Wraps as a JSON object (not a string).
* Whitespace trimmed.
* All payload data (including alert rows) is preserved.

***

### Using Both Together

When both mappers are configured:

1. Base payload is built
2. `field_mapper` transformations are applied
3. `payload_mapper` wraps the final payload

#### Example

```json
{
  "field_mapper": "event:type,alert:notification",
  "payload_mapper": "webhook_data"
}
```

**Result:**

```json
{
  "webhook_data": {
    "type": "alert_state_change",
    "notification": {...},
    "url_base": "https://..."
  }
}
```

***

### Limitations

* **Silent failures:** Invalid mappings only log warnings.
* **Type conflicts:** Cannot create nested paths through non-object fields.
* **Fixed order:** field\_mapper runs before payload\_mapper.

Processing order:

```
1. Build base payload
2. Add trigger rows
3. Apply field_mapper
4. Apply payload_mapper
```

***

### Best Practices

#### For field\_mapper

* Use descriptive names for destination fields.
* Prefer hierarchical mappings to group related data.
* Trim extra spaces.
* Test transformations using a sample webhook receiver.

#### For payload\_mapper

* Use when integrating with systems requiring a wrapper field.
* Choose a meaningful top-level name (e.g., `data`, `payload`, `notification`).

***

### Advanced Examples

#### 1. Complex Restructuring

```
field_mapper: "alert.name:incident.title,alert.severity:incident.priority,alert.rows:incident.data,event:meta.source,url_base:meta.origin"
```

**Result:**

```json
{
  "incident": {
    "title": "Database Connection Alert",
    "priority": "high",
    "data": [{ "timestamp": "2024-01-01T10:00:00Z", "value": 95 }]
  },
  "meta": {
    "source": "alert_state_change",
    "origin": "https://apica.company.com"
  },
  "alert": { "id": 123, "state": "triggered" }
}
```

#### 2. Combined with Wrapper

```json
{
  "field_mapper": "alert.name:notification.subject,alert.severity:notification.level",
  "payload_mapper": "webhook_payload"
}
```

**Result:**

```json
{
  "webhook_payload": {
    "notification": { "subject": "Alert Name", "level": "critical" },
    "event": "alert_state_change",
    "alert": {...},
    "url_base": "https://..."
  }
}
```

***

### Example Configurations

| Integration Type          | Example Mapper Configuration                       |
| ------------------------- | -------------------------------------------------- |
| **Slack-style**           | `{"field_mapper": "event:text,alert:attachments"}` |
| **Generic Wrapper**       | `{"payload_mapper": "payload"}`                    |
| **Microsoft Teams-style** | `{"field_mapper": "event:@type,alert:sections"}`   |


---

# 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.apica.io/autonomous-insights/alert-destinations/webhook/webhook-destination-field-and-payload-mappers.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.