Build and test
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.
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 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
Register a test webhook endpoint
In 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.
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.
Sign as the recipient
SignatureAPI records the signing request email without sending it. Open it in the Dashboard’s Emails view, follow the signing link, and complete the ceremony. For embedded signing, create a ceremony and open its URL instead.
Check the result
Your endpoint receives recipient.completed, envelope.completed and deliverable.generated. Download the signed PDF from the deliverable. 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.
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, with one entry per problem in errors. |
| Wrong state | Delete an in_progress envelope: 409 cannot-delete. |
| Rejection | Open the ceremony and reject the document. The recipient becomes rejected and you receive recipient.rejected. |
| Cancellation | 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 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. 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. 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 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 explains.
Keep live keys out of automated tests. A live envelope is legally binding, sends real email and counts toward your plan.