Skip to content

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.

Pipedream’s documentation announces that Workflows and String are shutting down on March 31, 2027. See Pipedream’s notice before you build on it.

Full code on GitHub: no-code/pipedream.

Before you start

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

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

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.

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

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

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