---
title: "Send Agreements From a Notion Database"
description: "Send a SignatureAPI agreement from a Notion database button or automation. Notion's Send webhook action calls an automation tool, which creates the envelope."
canonical: "https://signatureapi.com/docs/integrations/notion"
source: "https://signatureapi.com/docs/integrations/notion.md"
last_verified_api_version: "1.18.0"
---

# Send Agreements From a Notion Database

Send a SignatureAPI agreement from a Notion database button or automation. Notion's Send webhook action calls an automation tool, which creates the envelope.

_Last verified against API version 1.18.0._

Notion databases can start a flow from a button or an automation with the **Send webhook** action. Notion sends its own payload, not a SignatureAPI request body, so the webhook goes to an automation tool, and that tool's HTTP step creates the envelope. No SignatureAPI app is needed.

## 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 paid Notion plan. [Notion](https://www.notion.com/help/webhook-actions) offers webhook actions on paid plans only.
- An automation tool with an inbound webhook and an HTTP step: [Make](https://signatureapi.com/docs/integrations/make), [Zapier](https://signatureapi.com/docs/integrations/zapier/http-recipe) or [n8n](https://signatureapi.com/docs/integrations/n8n).

## Send the envelope

1. **Create a webhook in the tool**

   In your automation tool, create a webhook trigger and copy its URL.

2. **Add the Send webhook action**

   In a database button or database automation, click **Add action**, choose **Send webhook** and enter the tool's URL. In an automation you can select the properties to send, such as the signer's name and email. Notion sends only database page properties, never page contents, and webhooks only use `POST`.

3. **Create the envelope in the tool**

   Notion can't preview the payload, so trigger the action once and read what the tool received. Then add an HTTP step that sends this request, mapping the name, email and page id from the payload. Store the key in the tool's credential storage.

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 your tool'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": "notion",
       "page_id": "1a2b3c4d5e6f47a8b9c0d1e2f3a4b5c6"
     },
     "topics": [
       "no_code",
       "notion"
     ],
     "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.page_id` comes back in every webhook event for this envelope, and the `notion` topic lets an endpoint receive only these envelopes. Notion allows five webhook actions per automation.

## Get the result back

Build a second scenario or workflow in the same tool, as in [Make](https://signatureapi.com/docs/integrations/make#get-the-result-back).

1. **Register the tool's URL in SignatureAPI**

   Create a second inbound webhook in the tool. 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 `notion` topic. 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.

2. **Read the envelope before you act**

   Anyone who knows a webhook URL can call it, so read the envelope with your key before you update the page. Put the id from `data.envelope_id` in the URL:

   HTTP request step settings for the "Completed envelope" request:

   1. **Method**: GET
   2. **URL**: `https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56`
   3. **Header**: `X-API-Key: YOUR_API_KEY`

      Store the key in your tool's secret or credential storage when it has one.

3. **Update the page**

   Send a `PATCH` request to `https://api.notion.com/v1/pages/{page_id}` with your Notion connection token as a bearer token and a `Notion-Version` header, using `metadata.page_id` as the page id. Set a property with a body such as `{ "properties": { "Status": { "select": { "name": "Signed" } } } }` ([Notion reference](https://developers.notion.com/reference/patch-page)).

When `deliverable.status` is `generated`, `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. The same event can arrive twice, so skip a page that already shows Signed. See [Webhooks](https://signatureapi.com/docs/api/webhooks).

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

Sent for one Notion database page.

```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": "notion",
    "page_id": "1a2b3c4d5e6f47a8b9c0d1e2f3a4b5c6"
  },
  "topics": [
    "no_code",
    "notion"
  ],
  "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": "notion",
    "page_id": "1a2b3c4d5e6f47a8b9c0d1e2f3a4b5c6"
  },
  "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",
    "notion"
  ],
  "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.
