Automation platforms
Send Envelopes From Pipedream
Create SignatureAPI envelopes from a Pipedream workflow with a Node.js code step, and receive signing events with an HTTP trigger.
Pipedream runs your code, so this page uses a code step instead of a request form. No SignatureAPI app is needed: one Run custom code step creates the envelope with fetch, and an HTTP trigger in a second workflow receives the result.
Full code on GitHub: no-code/pipedream.
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.
- A workflow whose trigger event carries
id,nameandemail.
Send the envelope
Add a code step
Click + below your trigger and select Run custom code. The step defaults to Node.js (Node.js code).
Paste the code
Replace the step’s code with the code below. It follows Pipedream’s component format: props become fields in the step, and run receives steps and $ (Component API).
Fill in the props
Paste your test key into signatureapi_key. The prop is marked secret: true, which hides the input like a password field and stores the value encrypted. Leave base_url empty.
// Pipedream Node.js code step. Paste this whole file into a "Run custom code" step.
// Props appear in the step UI. The trigger event is read from steps.trigger.event.
// ---- core: platform-agnostic ----
const DOC_URL = 'https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf';
const DEFAULT_BASE_URL = 'https://api.signatureapi.com';
function buildEnvelopePayload(event) {
return {
title: `Service Agreement - ${event.name}`,
message: 'Please review and sign the service agreement.',
metadata: { source: 'pipedream', record_id: String(event.id) },
topics: ['no_code', 'pipedream'],
documents: [
{
key: 'service_agreement',
url: DOC_URL,
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: event.name, email: event.email }],
};
}
async function createEnvelope(cfg, payload) {
const response = await fetch(`${(cfg.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '')}/v1/envelopes`, {
method: 'POST',
headers: { 'X-API-Key': cfg.apiKey, 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
});
const text = await response.text();
let data = null;
try { data = text ? JSON.parse(text) : null; } catch { data = { raw: text }; }
if (!response.ok) throw new Error(`POST /v1/envelopes failed with ${response.status}: ${(data && (data.detail || data.title)) || text}`);
return data;
}
// ---- end core ----
// ---- Pipedream shim: defineComponent, props, steps and $ come from Pipedream ----
export default defineComponent({
props: {
signatureapi_key: { type: 'string', label: 'SignatureAPI test API key', secret: true },
base_url: { type: 'string', label: 'API base URL (optional)', optional: true },
},
async run({ steps, $ }) {
const event = steps.trigger.event.body ?? steps.trigger.event;
const envelope = await createEnvelope({ apiKey: this.signatureapi_key, baseUrl: this.base_url }, buildEnvelopePayload(event));
$.export('envelope_id', envelope.id);
$.export('status', envelope.status);
return { id: envelope.id, status: envelope.status };
},
});The step reads steps.trigger.event.body when the trigger is an HTTP request, and the event itself otherwise. $.export makes envelope_id and status available to later steps as steps.<step name>.envelope_id, so store the id on your record. The step fails on any non-2xx answer and shows the API’s error.
Pipedream 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 Pipedream'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": "pipedream",
"record_id": "1042"
},
"topics": [
"no_code",
"pipedream"
],
"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"
}
]
}These are the settings of the request the code sends. data.envelope_metadata.record_id comes back in every webhook event, and the pipedream topic lets an endpoint receive only these envelopes.
Get the result back
Create an HTTP trigger
Start a second workflow with an HTTP trigger. Pipedream generates a unique endpoint URL for it, and a valid request gets a 200 OK by default (Triggers). The request body is available as event.body, parsed to an object when it is JSON.
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 pipedream 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.
Read the envelope before you act
The event body tells you which envelope changed, in data.envelope_id. By default anyone with the trigger URL can invoke the workflow, so read the envelope with your key before you update anything. Add a second code step with the same prop:
export default defineComponent({
props: {
signatureapi_key: { type: 'string', label: 'SignatureAPI test API key', secret: true },
},
async run({ steps, $ }) {
const id = steps.trigger.event.body.data.envelope_id;
const response = await fetch(`https://api.signatureapi.com/v1/envelopes/${id}`, {
headers: { 'X-API-Key': this.signatureapi_key },
});
if (!response.ok) throw new Error(`GET /v1/envelopes failed with ${response.status}`);
const envelope = await response.json();
$.export('deliverable_status', envelope.deliverable?.status ?? null);
return envelope;
},
});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, Zapier 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": "pipedream",
"record_id": "1042"
},
"topics": [
"no_code",
"pipedream"
],
"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": "pipedream",
"record_id": "1042"
},
"topics": [
"no_code",
"pipedream"
],
"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": "pipedream",
"record_id": "1042"
},
"topics": [
"no_code",
"pipedream"
],
"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": "pipedream",
"record_id": "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",
"pipedream"
],
"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.