> ## Documentation Index
> Fetch the complete documentation index at: https://developers.conveyour.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Response Operations

> Let your endpoint write contact fields back to ConveYour on a successful webhook response.

When a ConveYour workflow sends an **Outbound Webhook** to a third-party endpoint, that endpoint can optionally respond with a JSON payload that tells ConveYour to update fields on the contact that triggered the webhook.

This enables lightweight integrations where the external service can "write back" results — IDs, statuses, enrichment values — **without** building a custom inbound integration.

## How it works

<Steps>
  <Step title="Workflow sends outbound webhook">
    Your workflow sends an outbound webhook request to your endpoint.
  </Step>

  <Step title="Your endpoint responds">
    Your endpoint returns a normal HTTP response. If it returns **HTTP 200 or 202** and includes a `conveyour` block in the response body, ConveYour will read it.
  </Step>

  <Step title="ConveYour applies the operations">
    ConveYour validates the response operations and applies the requested updates to the same contact that triggered the webhook.
  </Step>
</Steps>

<Note>
  Response operations are **opt-in** per webhook trigger, processed **asynchronously** (the workflow continues while the write-back happens moments later), and restricted to fields you explicitly allowlist.
</Note>

***

## Enable response operations

In the webhook trigger settings:

1. Turn on **Process response operations**.
2. Select one or more **Allowed fields** (the allowlist).

<Warning>
  If response operations are enabled but **no allowed fields** are selected, the trigger cannot be saved.
</Warning>

***

## Response format

Return JSON with a top-level `conveyour` object:

```json theme={null}
{
  "conveyour": {
    "version": "1.0",
    "operations": [
      {
        "type": "set_info",
        "args": {
          "key": "your_field_key",
          "value": "your value"
        }
      }
    ]
  }
}
```

### Fields

<ParamField body="conveyour.version" type="string" required>
  The response operations version. Currently only `"1.0"` is supported.
</ParamField>

<ParamField body="conveyour.operations" type="array" required>
  A list of operations to apply. Maximum **10** operations per response.
</ParamField>

***

## Supported operations

### `set_info`

Sets a contact field value.

```json theme={null}
{
  "type": "set_info",
  "args": {
    "key": "checkr_status",
    "value": "clear"
  }
}
```

<ParamField body="args.key" type="string" required>
  The contact field to update. Must be one of the **Allowed fields** configured on the webhook trigger.
</ParamField>

<ParamField body="args.value" type="string" required>
  The value to set. Treated as a literal value — no Liquid templating is applied.
</ParamField>

**Rules**

* If you include the same `key` multiple times, the **last value wins**.
* Values are literal — no Liquid evaluation.
* Scalars and arrays are accepted; a JSON **object** as `value` is rejected.

<Warning>
  **Operations are all-or-nothing.** If any operation in the batch is invalid — a missing `key`, a field not on the allowlist, a missing `value`, an object `value`, or an unknown `type` — ConveYour discards the **entire** batch. Valid operations earlier in the array are not applied either, because all changes are staged and saved once at the end.

  Do not treat a partially-applied result as possible: either every operation lands, or none does.
</Warning>

***

## HTTP behavior and error handling

### When are operations applied?

ConveYour applies operations only when:

* The outbound webhook call returns **HTTP 200 or 202**, and
* Response operations are **enabled** for that webhook trigger, and
* The response body contains a valid `conveyour` block with a supported `version` and valid `operations`

### What happens on failure?

| Scenario | Result |
| - | - |
| Webhook request fails (any code other than 200/202, or a timeout) | Webhook becomes eligible for retry as configured; **no** operations applied |
| Webhook succeeds (200/202) but response operations invalid | Webhook already succeeded; the whole batch is discarded — **no retry** |

Reasons the batch is discarded:

* Invalid JSON
* Missing `conveyour` block
* Unsupported `version` (only `"1.0"` is accepted)
* More than 10 operations
* Unknown operation `type` (only `set_info` is supported)
* `set_info` uses a field not on the allowlist
* `set_info` is missing `key` or `value`, or `value` is an object

<Note>
  Failures are logged on the ConveYour side but are **not** reported back to your endpoint — your service gets no signal that its write-back was rejected. If a write-back matters, verify it with a follow-up `GET /api/contacts/:id`.
</Note>

***

## Example: write back an external ID

If your endpoint creates a record in an external system and wants to store the generated ID on the contact:

```json theme={null}
{
  "conveyour": {
    "version": "1.0",
    "operations": [
      {
        "type": "set_info",
        "args": {
          "key": "external_system_id",
          "value": "abc_12345"
        }
      }
    ]
  }
}
```

Your endpoint can include other top-level keys for its own purposes — ConveYour only reads the `conveyour` block.

***

## FAQ

<AccordionGroup>
  <Accordion title="Which contact is updated?">
    The same contact that triggered the webhook.
  </Accordion>

  <Accordion title="Will the next workflow step see the updated fields immediately?">
    Not necessarily. Response operations are processed asynchronously, so later workflow steps may run before the updates are applied.
  </Accordion>

  <Accordion title="Can my endpoint update any contact field?">
    No. Your webhook trigger includes an **allowlist** of fields that are permitted to be updated. Only fields on that list can be set via response operations.
  </Accordion>

  <Accordion title="Can I use multiple operations in one response?">
    Yes, up to **10** operations in a single response.
  </Accordion>

  <Accordion title="Can I return other JSON alongside the conveyour block?">
    Yes. Your endpoint can include other top-level keys for its own purposes. ConveYour only reads the `conveyour` block and ignores everything else.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.