---
title: "Send Envelopes From Tray"
description: "Create SignatureAPI envelopes from a Tray workflow with the HTTP Client connector, and receive signing events with a Webhook trigger."
canonical: "https://signatureapi.com/docs/integrations/tray"
source: "https://signatureapi.com/docs/integrations/tray.md"
last_verified_api_version: "1.18.0"
---

# Send Envelopes From Tray

Create SignatureAPI envelopes from a Tray workflow with the HTTP Client connector, and receive signing events with a Webhook trigger.

_Last verified against API version 1.18.0._

Tray calls the SignatureAPI REST API through its own **HTTP Client** connector. No SignatureAPI app is needed: one **POST** step creates the envelope, and a **Webhook** trigger in a second workflow 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. **Add the HTTP Client step**

   Add an **HTTP Client** step and set the operation to `POST`. Enter `https://api.signatureapi.com/v1/envelopes` in **URL** ([HTTP Client](https://tray.ai/documentation/connectors/core/http-client)).

2. **Add the key header**

   In **Headers**, add `X-API-Key`. Tray advises against typing credentials into the step: use a Generic Service Authentication and reference it with `$.auth`, for example `$.auth.api_key`. Also add `Content-Type` with `application/json`, because Tray sets the content type from the body unless you set it in the header.

3. **Set the body**

   Put the JSON below in the step's **Body**, in the raw property of the body. Tray's POST sample shows the payload there ([HTTP Client operations](https://tray.ai/documentation/connectors/core/http-client/http-client-operations-sample-payloads)). Map the recipient's name and email, and your record id, from earlier steps. Run the step once and check the response.

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

1. **Method**: POST
2. **URL**: `https://api.signatureapi.com/v1/envelopes`
3. **Header**: `X-API-Key: YOUR_API_KEY`

   Store the key in Tray's secret or credential storage when it has one.
4. **Header**: `Content-Type: application/json`
5. **Body (raw JSON)**:

   ```json
   {
     "title": "Service Agreement - Jane Doe",
     "message": "Please review and sign the service agreement.",
     "metadata": {
       "source": "tray",
       "record_id": "rec_1042"
     },
     "topics": [
       "no_code",
       "tray"
     ],
     "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"
       }
     ]
   }
   ```

`data.envelope_metadata.record_id` comes back in every webhook event for this envelope, and the `tray` topic lets an endpoint receive only these envelopes. From version 5.0 the HTTP Client step fails on any status outside `2xx`, so a `422` stops the run and shows the error.

## Get the result back

1. **Create the Webhook trigger**

   Start a second workflow with the **Webhook** trigger, open the trigger step options and choose **Copy public URL**. Click **Enable** before the first delivery ([Webhook Trigger](https://tray.ai/documentation/connectors/triggers/webhook-trigger)). Leave the response mode on **Auto respond with HTTP 200**, which replies immediately.

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 `tray` topic so only envelopes from this workflow 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. Then use **Debug** on the trigger to see the first payload.

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 an **HTTP Client** step with the `GET` operation and the same header, and put the envelope id from the event in the URL:

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

   1. **Method**: GET
   2. **URL**: `https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56`
   3. **Header**: `X-API-Key: YOUR_API_KEY`

      Store the key in Tray's secret or credential storage when it has one.

   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.

SignatureAPI expects a `2XX` answer and 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), [Workato](https://signatureapi.com/docs/integrations/workato) and [n8n](https://signatureapi.com/docs/integrations/n8n) use the same request.

### Example: Service agreement

Sent from a Tray HTTP Client step.

```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": "tray",
    "record_id": "rec_1042"
  },
  "topics": [
    "no_code",
    "tray"
  ],
  "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": "tray",
    "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",
    "tray"
  ],
  "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.
