---
title: "Test Your Integration"
description: "Test a SignatureAPI integration end to end in test mode: no emails reach recipients, sign through the Dashboard, check webhooks, and keep CI offline."
canonical: "https://signatureapi.com/docs/api/guides/how-to/test-your-integration"
source: "https://signatureapi.com/docs/api/guides/how-to/test-your-integration.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:35:44Z"
---

# Test Your Integration

Test a SignatureAPI integration end to end in test mode: no emails reach recipients, sign through the Dashboard, check webhooks, and keep CI offline.

_Last verified against API version 1.18.0._

Test mode runs the same API as live mode, with the same validation, statuses and events. It sends no emails and costs nothing, so you can run the whole flow without reaching a real person. This guide walks through one end-to-end test and then shows what to automate.

## Use a Test Key

Requests with a `key_test_` key create test envelopes. Everything a test key touches stays in test mode: envelopes, webhook endpoints, senders and events. See [Test Mode](https://signatureapi.com/docs/api/test-mode) for the full list of differences.

Use any recipient address. Test mode never delivers the email, so the address doesn't need a mailbox. The examples in these docs use `jane.doe@example.com`.

## Run One Envelope End to End

1. **Register a test webhook endpoint**

   In [Settings > Webhooks](https://dashboard.signatureapi.com/settings/webhooks), turn on Test Mode and add an endpoint. Only test envelopes send events to it. To receive events on your machine, use a tunnel from [Webhooks > Tools](https://signatureapi.com/docs/api/webhooks#tools).

2. **Create an envelope**

   Send `POST /v1/envelopes` with your test key. The response has status `processing`. Your endpoint then receives `envelope.created` and `envelope.started`, and the envelope moves to `in_progress`.

3. **Sign as the recipient**

   SignatureAPI records the signing request email without sending it. Open it in the Dashboard's [Emails view](https://dashboard.signatureapi.com/emails?mode=test), follow the signing link, and complete the ceremony. For embedded signing, [create a ceremony](https://signatureapi.com/docs/api/resources/ceremonies/create) and open its URL instead.

4. **Check the result**

   Your endpoint receives `recipient.completed`, `envelope.completed` and `deliverable.generated`. Download the signed PDF from the [deliverable](https://signatureapi.com/docs/api/resources/deliverables/object). Test documents carry a "non-binding test document" notice on every page.

Events can arrive in any order and more than once, so test those cases too. See [Idempotent webhook processing](https://signatureapi.com/docs/api/guides/best-practices/idempotent-webhooks).

## Test Failure Paths

Exercise the responses your code must handle, all in test mode:

| Case             | How to trigger it                                                                                                                                                      |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Validation error | Create an envelope without `recipients`: `422` [`validation-error`](https://signatureapi.com/docs/v1/errors/validation-error), with one entry per problem in `errors`. |
| Wrong state      | Delete an `in_progress` envelope: `409` [`cannot-delete`](https://signatureapi.com/docs/v1/errors/cannot-delete).                                                      |
| Rejection        | Open the ceremony and reject the document. The recipient becomes `rejected` and you receive `recipient.rejected`.                                                      |
| Cancellation     | [Cancel](https://signatureapi.com/docs/api/resources/envelopes/cancel) an `in_progress` envelope. You receive `envelope.canceled`.                                     |
| Bad signature    | Send your webhook handler a request with a changed body. It must answer with a `4XX` status.                                                                           |

[Retries and errors](https://signatureapi.com/docs/api/guides/how-to/retries-and-errors) explains which of these to retry.

## Complete an Envelope Without Signing

To test what happens after completion without opening a ceremony, create an envelope whose only recipient is an [automatic signer](https://signatureapi.com/docs/api/resources/recipients/automatic-signer). SignatureAPI applies its signature, and the envelope completes on its own.

## What to Automate

- **Webhook handler.** Unit test it with signed fixtures: sign a sample payload with a secret you choose, using the steps in [Verify webhook signatures](https://signatureapi.com/docs/api/guides/how-to/verify-webhooks#how-verification-works). Cover a valid delivery, a changed body, an old timestamp and a repeated event `id`. These tests need no network.
- **API calls.** Mock the API at your HTTP client and record real test-mode responses as fixtures. The [OpenAPI specification](https://signatureapi.com/docs/api/openapi) describes every response, so you can validate fixtures against it.
- **The end-to-end flow.** Run the steps above with your test key before each release. A browser automation tool can drive the ceremony from the signing link; it must produce real input, as [Automated testing](https://signatureapi.com/docs/embedded/introduction#automated-testing) explains.

Keep live keys out of automated tests. A live envelope is legally binding, sends real email and counts toward your plan.
