Skip to content

Automation platforms

Send Envelopes From Tray

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

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

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).

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). 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.

SettingValue
Method POST
URL https://api.signatureapi.com/v1/envelopes
Header X-API-Key: YOUR_API_KEY

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

Header Content-Type: application/json
Body (raw JSON)The JSON below.
Body (raw 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). 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 in test mode with that URL. Subscribe to deliverable.generated, which fires when the signed PDF is ready, and add the tray topic so only envelopes from this workflow arrive. The envelope.completed 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.

SettingValue
Method GET
URL https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56
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, 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 for retries and duplicates.