# Webhook actions

## Developing a Webhook action

### Webhook request structure

```javascript
{
  "input_data": {
    "attributes": {
      "[attribute name]": "[attribute value]"
    }
  }
}
```

### Webhook response structure

#### Successful

```javascript
{
  "successful": true,
  "output_data": {
    "attributes": {
      "full_name": "John Smith"
    }
  }
}
```

#### Unsuccessful

```javascript
{
  "successful": false,
  "errors": [
    {
      "message": "[error message]"
    }
  ]
}
```

### Handling different attribute types

In OpenDialog we support a number of different attribute types and webhook action can be used with more than just key:value pairs. 

#### Composite Attributes

You can provide information as a JSON object in a reply to an OpenDialog Action. The attribute type within OpenDialog needs to be defined as `JSON Inferred Composite`. This indicates to the OpenDialog engine that it should attempt to infer all the different properties of the JSON object and map them to appropriate attributes. 

So for example you can provide the following payload as a response 

```
{
  "successful": true,
  "output_data": {
    "attributes": {
      "policy_info": {
        "number_of_policies": "3",
        "policy1": {
          "type": "motor_policy",
          "name": "John1",
          "surname": "Doe1",
          "policyID": "12345ABC"
        },
        "policy2": {
          "type": "motor_policy",
          "name": "John2",
          "surname": "Doe2",
          "policyID": "12345ABC"
        },
        "policy3": {
          "type": "motor_policy",
          "name": "John3",
          "surname": "Doe3",
          "policyID": "12345ABC"
        }
      }
    }
  }
}
```

OpenDialog will make this attribute available as a composite and you can access specific properties with the syntax `user.policy_info[number_of_policies]` or `user.policy_info[policy2][type]`, from within messages, etc. 

Attribute Collections

Attribute collections are lists of items. For lists you can declare that the attribute is of a collection type and then present the information as an array within the payload response to the action. 

```
{
  "successful": true,
  "output_data": {
    "attributes": {
      "collection_example": ["item1", "item2", "item3"],
    }
  }
}
```

You can then access collection data using the index -  for the above it would be `collection_example[0]` for retrieving `item1`, and so on. 

### Examples

#### Populating attributes

This example models an action which takes first & last name attributes and uses them to populate a full name attribute. As the action response specified that it was successful, this will also automatically populate the `action_success` attribute with `true`.

**Request**

```
{
  "input_data": {
    "attributes": {
      "first_name": "John",
      "last_name": "Smith",
    }
  }
}
```

**Response**

```
{
  "successful": true,
  "output_data": {
    "attributes": {
      "full_name": "John Smith"
    }
  }
}
```

#### Unsetting attributes

This example models a successful action which takes feedback attributes and then returns `null` values for some of them, causing OpenDialog to unset those attributes. It is possible for an action response to both unset and populate attributes, they are not mutually exclusive. As the action response specified that it was successful, this will also automatically populate the `action_success` attribute with `true`.

**Request**

```javascript
{
  "input_data": {
    "attributes": {
      "location": "Bristol",
      "rating": 5,
      "comments": "Great service!"
    }
  }
}
```

**Response**

```javascript
{
  "successful": true,
  "output_data": {
    "attributes": {
      "rating": null,
      "comments": null,
      "referral_code": "ABCXYZ123"
    }
  }
}
```

#### Errors

This example models an unsuccessful action which has returned an error. As the action response specified that it was unsuccessful, this will also automatically populate the `action_success` attribute with `false`. The error message(s) will be automatically added to the logs.

**Request**

```javascript
{
  "input_data": {
    "attributes": {
      "location": "Bristol"
    }
  }
}
```

**Response**

```javascript
{
  "successful": false,
  "errors": [
    {
      "message": "Missing expected attributes: 'rating', 'comments'"
    }
  ]
}
```


---

# 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.opendialog.ai/~/changes/BlkAxgfqkBZsmUnZLd8K/developing-with-opendialog/actions/webhook-actions.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.