Automation platforms
Send Envelopes From Workato
Create SignatureAPI envelopes from a Workato recipe with the HTTP connector, and receive signing events with a webhook trigger.
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 (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
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).
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).
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.
| Setting | Value |
|---|---|
| Method | POST |
| Request URL | /v1/envelopes Relative to |
| Request content type | Raw JSON request body |
| Body (raw JSON) | The JSON below. |
{
"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.
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
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).
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 workato topic so only envelopes from this recipe arrive. The envelope.completed 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 to yourself and sign it.
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.
| Setting | Value |
|---|---|
| Method | GET |
| Request URL | / Relative to |
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.
A webhook trigger answers 200 with {"status":"ok"} by default (New event via HTTP webhook), 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 for retries and duplicates.
Related
- Create an envelope: every field of the request body.
- Organize with topics and metadata.
- Make, Tray 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": "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"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"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"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"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"
}
]
}
}{
"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
}{
"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.