---
title: "Send Envelopes From Pipedream"
description: "Create SignatureAPI envelopes from a Pipedream workflow with a Node.js code step, and receive signing events with an HTTP trigger."
canonical: "https://signatureapi.com/docs/integrations/pipedream"
source: "https://signatureapi.com/docs/integrations/pipedream.md"
last_verified_api_version: "1.18.0"
---

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

_Last verified against API version 1.18.0._

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.

> **Warning:** Pipedream's documentation announces that Workflows and String are shutting down on March 31, 2027. See [Pipedream's notice](https://pipedream.com/docs/workflows/building-workflows/triggers/) before you build on it.

Full code on GitHub: [`no-code/pipedream`](https://github.com/signatureapi/examples/tree/main/no-code/pipedream).

## 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.
- A workflow whose trigger event carries `id`, `name` and `email`.

## Send the envelope

1. **Add a code step**

   Click **+** below your trigger and select **Run custom code**. The step defaults to Node.js ([Node.js code](https://pipedream.com/docs/workflows/building-workflows/code/nodejs/)).

2. **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](https://pipedream.com/docs/components/contributing/api/)).

3. **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.

```javascript
// 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:

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

   Store the key in Pipedream'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": "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

1. **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](https://pipedream.com/docs/workflows/building-workflows/triggers/)). The request body is available as `event.body`, parsed to an object when it is JSON.

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 `pipedream` 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.

3. **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:

   ```javascript
   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](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), [Zapier](https://signatureapi.com/docs/integrations/zapier/http-recipe) and [n8n](https://signatureapi.com/docs/integrations/n8n) use the same request.

### Example: Service agreement

The body the Pipedream code step sends.

```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": "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"
    }
  ]
}
```

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": "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
}
```

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.
