> For the complete documentation index, see [llms.txt](https://docs.wrangle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wrangle.io/integrations/wrangle-webhooks.md).

# Wrangle Webhooks

Using Wrangle Webhooks, you can listen for ticket and workflow events in Wrangle and respond to them in your own systems.

Wrangle Webhooks support the following top level event types:

* **Ticket Creation** - Triggered each time a new ticket is created.
* **Ticket Updates** - Triggered each time a ticket is updated.
* **Workflow Completions** - Triggered each time a workflow instance is completed.

### Getting Started

To use Wrangle Webhooks, you'll need to be an account admin for your organization.

1. Navigate to the [Webhooks page](https://slack.wrangle.io/integrations/webhooks) (Integrations > Webhooks).
2. Click `Create Webhook`.
3. Enter a Webhook URL: This must be a URL that you control that must respond with a 2xx status before Wrangle will start sending events to it.
4. Enter a Secret: Use this value in your application to verify that requests are from Wrangle. We will send all requests with a header in the format: `Authorization: Bearer <secret>`.
5. Choose which events to subscribe to.
   * **Inboxes** only apply to ticket events, and only show while a ticket event is turned on. If you don't select any inboxes, we'll send events from all inboxes (except those marked explicitly as [Confidential](https://docs.wrangle.io/tickets/setting-up-your-inbox/roles-and-permissions#confidential-inboxes-for-greater-privacy)).
   * **Workflows** only apply to workflow completions, and show once **Workflow completions** is turned on. Choose at least one workflow to send completions from.
     * To start a Slack workflow when a Wrangle workflow is completed, choose that one workflow and turn on **Format for Slack Workflow Builder?**. See [Sending workflow completions to Slack Workflow Builder](https://docs.wrangle.io/integrations/wrangle-webhooks.md#swb).

You can create more than one webhook, for example to send ticket events to one system and a workflow's completions to Slack Workflow Builder.

### Webhook POST Body Format

For each ticket event, you'll receive the contents of the relevant Wrangle ticket under the `ticket` property, formatted in exactly the same shape as the [Ticket body](https://docs.wrangle.io/integrations/wrangle-api/models#ticket) you receive via the [Wrangle API](https://docs.wrangle.io/integrations/wrangle-api.md).\
\
**Ticket Created:**

```
{
    occurredAt: {ISO_TIMESTAMP}, // ie 2026-09-08T17:35:41.397Z,
    activityType: 'ticketCreated',
    ticket: TICKET_BODY, // see https://docs.wrangle.io/integrations/wrangle-api/models#ticket
}
```

**Ticket Updated:**

```
{
    occurredAt: {ISO_TIMESTAMP}, // ie 2026-09-08T17:35:41.397Z,
    activityType: 'ticketUpdated',
    eventTypes : [], // types of updates. See below for details.
    ticket: TICKET_BODY, // see https://docs.wrangle.io/integrations/wrangle-api/models#ticket
}
```

You will receive updates for the following `eventTypes`:

* `ASSIGNMENT_CHANGE` - When a ticket is assigned to an agent, or marked as unassigned after being previously assigned.
* `CSAT_SUBMISSION` - When a [customer satisfaction survey](https://docs.wrangle.io/tickets/setting-up-your-inbox/ticket-lifecycle/ticket-resolution#customer-satisfaction-surveys) is submitted.
* `DESCRIPTION_CHANGE` - When the ticket's description is changed.
* `FOLLOWER_ADDED_VIA_MENTION` - When a ticket follower has been automatically added after being `@mentioned` in the Slack thread.
* `FOLLOWER_CHANGE` - When followers are added or removed.
* `INBOX_CHANGE` - When the ticket is moved to a different inbox.
* `NAME_CHANGE` - When the name of the ticket is changed.
* `PRIORITY_CHANGE` - When the ticket priority is changed.
* `STATUS_CHANGE` - When the ticket's status is changed.
* `TAGS_CHANGE` - When ticket tags are added or removed.
* `TICKET_CLAIM` - When an agent assigns a ticket to themselves.
* `WORKFLOW_SUGGEST` - When a Wrangle workflow is suggested to the ticket requester.

**Workflow Instance Completed:**

Sent once when a workflow instance finishes successfully. Instances that are canceled, or that end without completing, don't send this event.

```
{
    occurredAt: {ISO_TIMESTAMP}, // when the instance was completed, ie 2026-09-08T17:35:41.397Z
    activityType: 'workflowInstanceCompleted',
    workflow: {
        id: WORKFLOW_ID,
        name: 'Employee Onboarding',
    },
    instance: {
        id: INSTANCE_ID,
        number: 42, // the instance number shown in Wrangle
        name: 'Jane Smith', // the instance name
        creationSource: 'SLACK', // how the instance was started, ie SLACK, WEB, PUBLIC_API, or ZAPIER
        startedAt: {ISO_TIMESTAMP},
        completedAt: {ISO_TIMESTAMP},
        requester: { // the person who started the instance
            id: SLACK_USER_ID, // their Slack user ID
            email: 'jane@example.com',
            name: 'Jane Smith',
        },
        formData: { // answers from every form in the instance, keyed by question ID. See below.
            QUESTION_ID: {
                label: 'Employee name',
                value: 'Jane Smith',
            },
            QUESTION_ID: {
                label: 'Equipment needed',
                value: ['Laptop', 'Monitor'], // multi-select questions
            },
            QUESTION_ID: {
                label: 'Number of monitors',
                value: 2, // number questions
            },
            QUESTION_ID: {
                label: 'Signed offer letter',
                value: ['https://slack.wrangle.io/workflows/WORKFLOW_ID/instances/INSTANCE_ID/files/FILE_KEY'], // file questions
            },
        },
        url: 'https://slack.wrangle.io/workflows/WORKFLOW_ID/instances/INSTANCE_ID',
    },
}
```

\
\
About `formData`:

* It includes the answers to the intake form and every later form step in the instance. If a form was resubmitted, you'll receive the latest answers.
* Each answer is keyed by its question ID and includes the question's `label` alongside its `value`. Match on the ID in your integration, since labels can be renamed at any time.
* Answers to file questions are links to the uploaded files in Wrangle. Opening them requires being signed in to Wrangle with access to the workflow instance.

### Sending workflow completions to Slack Workflow Builder <a href="#swb" id="swb"></a>

You can start a [Slack workflow](https://slack.com/help/articles/360041352714-Create-more-advanced-workflows-using-webhooks) each time a [Wrangle workflow](https://docs.wrangle.io/workflows/using-a-workflow#what-is-a-workflow) instance is completed. Slack's webhook triggers can only read top-level values, so Wrangle sends these webhooks in a different, flat format.

1. In Slack Workflow Builder, create a workflow that starts **From a webhook**, and copy its webhook URL. It starts with `https://hooks.slack.com/triggers/`.
2. On the [Webhooks page](https://slack.wrangle.io/integrations/webhooks), create or edit your webhook. Paste the Slack webhook URL and enter a secret. Slack doesn't check the secret, but Wrangle still sends it with every request.
3. Turn on **Workflow completions**, choose the one workflow whose completions should start your Slack workflow, then turn on **Format for Slack Workflow Builder?**.
4. Click **View Slack variables** to see every key this workflow sends, next to the question or detail it holds. In Slack, add a variable for each one you want to use, using the key as the variable's name. Use the **Text** data type for most keys, **User ID** for `instance_requester_id`, and **Email** for `instance_requester_email`.

This format only sends workflow completions, so ticket events are turned off and the inbox filter isn't available. Each Slack Workflow Builder webhook sends completions from exactly one workflow instance.

\
**Slack Workflow Builder body:**

```
{
    activity_type: 'workflowInstanceCompleted',
    occurred_at: '2026-09-08T17:35:41.397Z',
    workflow_id: WORKFLOW_ID,
    workflow_name: 'Employee Onboarding',
    instance_id: INSTANCE_ID,
    instance_number: '42',
    instance_name: 'Jane Smith',
    instance_creation_source: 'SLACK',
    instance_started_at: '2026-09-08T09:30:00.000Z',
    instance_completed_at: '2026-09-08T17:35:41.397Z',
    instance_requester_email: 'jane@example.com',
    instance_requester_id: 'U012AB3CD',
    instance_requester_name: 'Jane Smith',
    instance_url: 'https://slack.wrangle.io/workflows/WORKFLOW_ID/instances/INSTANCE_ID',
    form_QUESTION_ID: 'Jane Smith',
    form_QUESTION_ID: 'Laptop, Monitor',
    form_QUESTION_ID: '', // unanswered questions are sent as empty text
}
```

Every value is sent as a string, and every key is always sent, even when its value is empty. These keys hold the same information as the standard workflow completion body above:

* `activity_type` - Always `workflowInstanceCompleted`.
* `occurred_at` and `instance_completed_at` - When the instance was completed.
* `instance_started_at` - When the instance was started.
* `instance_number` - The instance number shown in Wrangle.
* `instance_creation_source` - How the instance was started: `SLACK`, `WEB`, `PUBLIC_API`, or `ZAPIER`.
* `instance_requester_id`, `instance_requester_email`, and `instance_requester_name` - The Slack user ID, email, and name of the person who started the instance.
* `instance_url` - A link to the instance in Wrangle.

About the `form_` keys:

* There's one `form_` key for every question on the workflow's forms, including the intake form. **View Slack variables** lists each question's label next to its key, grouped by form step.
* The key is `form_` followed by the question's ID, with any character other than a letter, number, or underscore replaced by `_`. Renaming a question doesn't change its key.
* Questions that weren't answered, for example on a skipped conditional step, are sent as empty text so your Slack workflow still runs.
* Answers with more than one value, such as multi-select questions, are joined with a comma and a space. Answers to file questions are links to the uploaded files in Wrangle.

### Recipes

For a step-by-step example of integrating Wrangle Webhooks with Slack Workflow Builder, learn how to automatically add someone to a Slack channel after their request is approved in Wrangle:

{% content-ref url="/pages/uXlsBKDuIiJhAcb89V4o" %}
[Recipe: Automatically add a user to a Slack channel after approvals using Slack Workflow Builder](https://docs.wrangle.io/best-practices/recipes/recipe-automatically-add-a-user-to-a-slack-channel-after-approvals-using-slack-workflow-builder.md)
{% endcontent-ref %}

Or learn how to send each completed workflow instance's data to a Google Sheet:

{% content-ref url="/pages/YUhfu6A9YAoNG0N6QRpe" %}
[Recipe: Send your completed workflow data to Google Sheets using Slack Workflow Builder](https://docs.wrangle.io/best-practices/recipes/recipe-send-your-completed-workflow-data-to-google-sheets-using-slack-workflow-builder.md)
{% endcontent-ref %}
