---
title: "Send Envelopes From Workato"
description: "Create SignatureAPI envelopes from a Workato recipe with the HTTP connector, and receive signing events with a webhook trigger."
canonical: "https://signatureapi.com/docs/integrations/workato"
source: "https://signatureapi.com/docs/integrations/workato.md"
last_verified_api_version: "1.18.0"
---

# Send Envelopes From Workato

Create SignatureAPI envelopes from a Workato recipe with the HTTP connector, and receive signing events with a webhook trigger.

_Last verified against API version 1.18.0._

Workato calls the SignatureAPI REST API through its own **HTTP** connector. No SignatureAPI app is needed: one **Send request via HTTP** action creates the envelope, and a **New event via HTTP webhook** trigger in a second recipe receives the result.

## Before you start

- A SignatureAPI [test API key](https://signatureapi.com/docs/api/test-mode) (it starts with `key_test_`).
- The document you send, at a URL on a [supported host](https://signatureapi.com/docs/api/resources/documents/url#external-store), or [uploaded to SignatureAPI](https://signatureapi.com/docs/api/resources/uploads/create) first. The examples use a sample PDF.

## Send the envelope

1. **Create an HTTP connection**

   Workato needs an HTTP connection before you configure the action. Set **Base URL** to `https://api.signatureapi.com`, and set **Authentication type** to **Header auth**. Expand **Header authorization** and add the `X-API-Key` header with your key. The connection keeps the key out of the recipe ([HTTP connection setup](https://docs.workato.com/en/developing-connectors/http/connection-setup)).

2. **Add the action**

   In the recipe, add the **HTTP** connector's **Send request via HTTP** action and click **Setup manually**. Set **Method** to `POST`, and enter `/v1/envelopes` in **Request URL**. Workato accepts a relative URL when the connection sets a base URL ([Send request via HTTP](https://docs.workato.com/en/developing-connectors/http/building-http-action)).

3. **Set the body**

   Set **Request content type** to **Raw JSON request body**, which lets you enter the payload directly. Paste the body below and map the recipient's name and email, and your record id, from earlier steps.

Workato HTTP request step settings for the "Service agreement" request:

1. **Method**: POST
2. **Request URL**: `/v1/envelopes`

   Relative to `https://api.signatureapi.com`. The base URL and the API key come from the setup in the steps above.
3. **Request content type**: Raw JSON request body
4. **Body (raw JSON)**:

   ```json
   {
     "title": "Service Agreement - Jane Doe",
     "message": "Please review and sign the service agreement.",
     "metadata": {
       "source": "workato",
       "record_id": "rec_1042"
     },
     "topics": [
       "no_code",
       "workato"
     ],
     "documents": [
       {
         "key": "service_agreement",
         "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
         "format": "pdf",
         "fixed_positions": [
           {
             "place_key": "signer_signature",
             "page": 1,
             "top": 172,
             "left": 210
           }
         ],
         "places": [
           {
             "key": "signer_signature",
             "type": "signature",
             "recipient_key": "signer"
           }
         ]
       }
     ],
     "recipients": [
       {
         "type": "signer",
         "key": "signer",
         "name": "Jane Doe",
         "email": "jane.doe@example.com"
       }
     ]
   }
   ```

Setting names as in the [Workato documentation](https://docs.workato.com/en/developing-connectors/http/building-http-action).

`data.envelope_metadata.record_id` comes back in every webhook event for this envelope, and the `workato` topic lets an endpoint receive only these envelopes.

## Get the result back

1. **Create the webhook trigger**

   Start a second recipe with the **Trigger from a webhook** starting point, which uses the **New event via HTTP webhook** trigger. Click **Start guided setup**, enter an **Event name** and click **Next**. The webhook URL appears on the listening screen, where you click **Copy** ([Create a webhook with the wizard](https://docs.workato.com/en/connectors/workato-webhooks/wizard)).

2. **Register the URL in SignatureAPI**

   In the Dashboard, add a [webhook endpoint](https://signatureapi.com/docs/api/guides/how-to/set-up-webhooks) in test mode with that URL. Subscribe to [`deliverable.generated`](https://signatureapi.com/docs/api/resources/events/deliverable-events#deliverablegenerated), which fires when the signed PDF is ready, and add the `workato` topic so only envelopes from this recipe arrive. The [`envelope.completed`](https://signatureapi.com/docs/api/resources/events/envelope-events#envelopecompleted) event comes earlier, while the PDF may still be generating, so use it only to update a status. The wizard waits for a first event: send a [test envelope](https://signatureapi.com/docs/api/test-mode) to yourself and sign it.

3. **Read the envelope before you act**

   The event body tells you which envelope changed, in `data.envelope_id`. Anyone who knows the webhook URL can call it, so read the envelope with your key before you update anything. Add a **Send request via HTTP** action on the same connection, and put the envelope id from the event in the URL:

   Workato HTTP request step settings for the "Completed envelope" request:

   1. **Method**: GET
   2. **Request URL**: `/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56`

      Relative to `https://api.signatureapi.com`. The base URL and the API key come from the setup in the steps above.

   Act on the response: `deliverable.status` is `generated`, `metadata.record_id` names your record, and `deliverable.url` downloads the signed PDF. That link expires after an hour, so download the file in the same run. If your account uses [authenticated deliverable URLs](https://signatureapi.com/docs/api/resources/deliverables/object#url), send your API key with the download.

A webhook trigger answers `200` with `{"status":"ok"}` by default ([New event via HTTP webhook](https://docs.workato.com/en/connectors/workato-webhooks/config)), which SignatureAPI treats as acknowledged. The trigger ignores events while the recipe is stopped, and SignatureAPI retries a failed delivery for up to 48 hours. The same event can arrive twice: skip it if your record already has the signed PDF. See [Webhooks](https://signatureapi.com/docs/api/webhooks) for retries and duplicates.

## Related

- [Create an envelope](https://signatureapi.com/docs/api/resources/envelopes/create): every field of the request body.
- [Organize with topics and metadata](https://signatureapi.com/docs/api/guides/how-to/organize-topics-metadata).
- [Make](https://signatureapi.com/docs/integrations/make), [Tray](https://signatureapi.com/docs/integrations/tray) and [n8n](https://signatureapi.com/docs/integrations/n8n) use the same request.

### Example: Service agreement

Sent from a Workato HTTP action.

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Service Agreement - Jane Doe",
  "message": "Please review and sign the service agreement.",
  "metadata": {
    "source": "workato",
    "record_id": "rec_1042"
  },
  "topics": [
    "no_code",
    "workato"
  ],
  "documents": [
    {
      "key": "service_agreement",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "place_key": "signer_signature",
          "page": 1,
          "top": 172,
          "left": 210
        }
      ],
      "places": [
        {
          "key": "signer_signature",
          "type": "signature",
          "recipient_key": "signer"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "signer",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  ]
}
```

Response 201 Created:

```json
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Service Agreement - Jane Doe",
  "label": null,
  "message": "Please review and sign the service agreement.",
  "status": "processing",
  "attestation": "none",
  "language": "en",
  "mode": "test",
  "routing": "sequential",
  "timezone": "UTC",
  "timestamp_format": "MM/DD/YYYY HH:mm:ss",
  "snapshot_url": null,
  "branding": {
    "logo": null,
    "accent_color": "#2463EB",
    "email": {
      "footer": null,
      "logo_position": "left",
      "from": "noreply@signatureapi.com"
    }
  },
  "deliverable": {
    "id": "del_6FF89lKNyTNamOJCJd1tLL",
    "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "name": null,
    "status": "pending",
    "type": "standard",
    "url": null,
    "password": null,
    "created_at": "2026-11-02T14:03:11.000Z",
    "generated_at": null,
    "timezone": "UTC",
    "language": "en",
    "timestamp_format": "MM/DD/YYYY HH:mm:ss",
    "included_documents": [
      "service_agreement"
    ]
  },
  "metadata": {
    "source": "workato",
    "record_id": "rec_1042"
  },
  "sender": {
    "name": "Acme Corp Legal",
    "email": "legal@acme.example",
    "organization": "Acme Corp"
  },
  "captures": {},
  "documents": [
    {
      "id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "key": "service_agreement",
      "title": null,
      "page_count": 1,
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "page": 1,
          "top": 172,
          "left": 210,
          "place_key": "signer_signature"
        }
      ],
      "places": [
        {
          "key": "signer_signature",
          "type": "signature",
          "recipient_key": "signer",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_49r1R2jpPDz8hSpP75ZkPp",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "signer",
      "key": "signer",
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "ceremony": {
        "authentication": [
          {
            "type": "email_link",
            "subject_override": null,
            "message_override": null
          }
        ],
        "embeddable_in": [],
        "redirect_url": null,
        "redirect_delay": 3,
        "url": null,
        "url_variant": "standard"
      },
      "ceremony_creation": "automatic",
      "delivery_type": "email",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "status": "pending",
      "status_updated_at": "2026-11-02T14:03:11.000Z",
      "completed_at": null
    }
  ],
  "topics": [
    "no_code",
    "workato"
  ],
  "created_at": "2026-11-02T14:03:11.000Z",
  "completed_at": null
}
```

Response 422 Unprocessable Content:

```json
{
  "type": "https://signatureapi.com/docs/v1/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "errors": [
    "recipients[0].email must be a valid email address."
  ]
}
```

Errors that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
