Webhook Response Operations

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

Workflow sends outbound webhook

Your workflow sends an outbound webhook request to your endpoint.

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.

ConveYour applies the operations

ConveYour validates the response operations and applies the requested updates to the same contact that triggered the webhook.

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.

Enable response operations

In the webhook trigger settings:

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

If response operations are enabled but no allowed fields are selected, the trigger cannot be saved.

Response format

Return JSON with a top-level conveyour object:

{
  "conveyour": {
    "version": "1.0",
    "operations": [
      {
        "type": "set_info",
        "args": {
          "key": "your_field_key",
          "value": "your value"
        }
      }
    ]
  }
}

Fields

string

required

The response operations version. Currently only "1.0" is supported.

array

required

A list of operations to apply. Maximum 10 operations per response.

Supported operations

`set_info`

Sets a contact field value.

{
  "type": "set_info",
  "args": {
    "key": "checkr_status",
    "value": "clear"
  }
}

string

required

The contact field to update. Must be one of the Allowed fields configured on the webhook trigger.

string

required

The value to set. Treated as a literal value — no Liquid templating is applied.

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.

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.

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

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.

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:

{
  "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

Which contact is updated?

The same contact that triggered the webhook.

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.

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.

Can I use multiple operations in one response?

Yes, up to 10 operations in a single response.

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.

Getting Started

Guides

How it works

Enable response operations

Response format

Fields

Supported operations

`set_info`

HTTP behavior and error handling

When are operations applied?

What happens on failure?

Example: write back an external ID

FAQ

​How it works

​Enable response operations

​Response format

​Fields

​Supported operations

​set_info

​HTTP behavior and error handling

​When are operations applied?

​What happens on failure?

​Example: write back an external ID

​FAQ

How it works

Enable response operations

Response format

Fields

Supported operations

`set_info`

HTTP behavior and error handling

When are operations applied?

What happens on failure?

Example: write back an external ID

FAQ