Skip to content

Ceremonies

Redirect URL

Configure where recipients are sent after they complete or decline a signing ceremony, and how to confirm the outcome.

After a standalone ceremony ends because the recipient completed or declined it, SignatureAPI redirects the recipient to the redirect_url you defined on the ceremony object.

SignatureAPI appends the following query parameters to the URL:

ParameterDescription
ceremony_resultThe outcome: ceremony.completed or ceremony.declined.
envelope_idThe ID of the envelope.
recipient_idThe ID of the recipient.

For example, if redirect_url is https://www.example.com, a successful ceremony redirects to:

https://www.example.com/?ceremony_result=ceremony.completed&envelope_id=5b7be28c-6c7c-4aaa-b25f-66879e8d0957&recipient_id=re_0sgQC0cejYRC8wRsT5N9ll

Redirect after a standalone ceremony
Signer's browser
Ceremony page
Your server
SignatureAPI API
  1. Signer's browser to Ceremony page: Finish or decline the ceremony
  2. Ceremony page to Signer's browser: Show the result page
  3. Signer's browser to Your server: Redirect to redirect_url
  4. Your server to SignatureAPI API: Get Envelope GET /v1/envelopes/{envelope_id}
  5. SignatureAPI API to Your server: Envelope with the recipient status
  1. Show the result page

    It stays for redirect_delay seconds (3 by default).

  2. Redirect to redirect_url

    SignatureAPI appends ceremony_result, envelope_id and recipient_id to the URL.

    Show the request
    HTTP
    GET /signing-complete?ceremony_result=ceremony.completed&envelope_id=5b7be28c-6c7c-4aaa-b25f-66879e8d0957&recipient_id=re_0sgQC0cejYRC8wRsT5N9ll HTTP/1.1
    Host: www.example.com
  3. Get Envelope GET /v1/envelopes/{envelope_id}

    The query parameters come from the browser, so don't trust them. Read the recipient status from the API.

  4. Envelope with the recipient status

    completed or rejected. A webhook such as recipient.completed confirms it too.

Dashed: a reply, or an asynchronous call such as a webhook.

The query parameters are not authenticated. Anyone can open your redirect_url with any ceremony_result, envelope_id and recipient_id. Don’t mark an envelope as signed because of them. Use the IDs to look up the envelope with Get Envelope, or wait for the recipient.completed or recipient.rejected webhook, and trust the recipient status they report.

The redirect happens only when the recipient completes or declines. If the ceremony fails or the recipient closes the page, no redirect occurs, so use the API or a webhook for those cases too.

Redirect delay

By default, the result page shows for 3 seconds before the redirect. Set the redirect_delay property to change this.

HTTP
POST /v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/ceremonies HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
    "authentication": [{ "type": "email_code" }],
    "redirect_url": "https://www.example.com/success",
    "redirect_delay": 0
}

Set redirect_delay to 0 for an immediate redirect. The maximum value is 20 seconds.

For embedded ceremonies, redirect_delay controls how long the result page shows before the ceremony sends ceremony.completed or ceremony.declined. Set it to 0 to hand control back to your app immediately, so your app can show its own result screen. Learn more in Ceremony Events.

Embedded ceremonies (with embedded=true on the URL) ignore redirect_url: leave it unset. They send Ceremony Events instead, including in native mobile apps.