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
- A SignatureAPI test API key (it starts with
key_test_). - The document you send, at a URL on a supported host, or uploaded to SignatureAPI first. The examples use a sample PDF.
Send the envelope
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).
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.
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.
| Setting | Value |
|---|---|
| Method | POST |
| URL | https:// |
| Header | X-API-Key: YOUR_API_KEY Store the key in Tray's secret or credential storage when it has one. |
| Header | Content- |
| Body (raw JSON) | The JSON below. |
{
"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
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.
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.
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.
| Setting | Value |
|---|---|
| Method | GET |
| URL | https:// |
| 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.
Related
- Create an envelope: every field of the request body.
- Organize with topics and metadata.
- Make, Workato and n8n use the same request.
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"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"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"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"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"
}
]
}
}{
"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
}{
"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 every call can return are in Errors and Authentication.