1. Overview
  2. Get started
  3. Add a webhook
  4. Testing your webhook
  5. Retry attempts
  6. Response codes
  7. Events
  8. Request sent
  9. Request completed
  10. Request archived
  11. Request deleted
  12. Contact created
  13. Signer signed
  14. Email delivered
  15. Email bounced
  16. Email spammed

Webhooks


Webhooks are HTTP endpoints that receive events from InsertSign.

They allow you to be notified about document collection events that happen in the real world outside of your document flow. Some examples of document collection events include completed requests (request.completed) and bounced emails (email.bounced).

Webhooks are essential for scaling your document collection integration by helping you process large volumes of business-critical events.

Overview

Get started

A webhook is the act of InsertSign making an HTTP POST request to your application’s API when an event occurs. This way InsertSign is able to immediately notify you when an event occurs.

You can build a webhook handler on your own server to manage all your offline workflows. Start by exposing an endpoint that can receive requests from InsertSign and test your integration. Each request from InsertSign contains an JSON object with a reference to the object on InsertSign that was modified.

Add a webhook

Navigate to Settings > Webhooks and click the Add an endpoint button. Enter an endpoint URL and select the events you want to listen to. Click Save to finish setting up a new webhook.

Testing your webhook

Testing webhooks can be a difficult process. Here are two recommendations:

Using the dashboard:

Navigate to Settings > Webhooks and click the ... three dots to reveal an option to test your URL endpoint. Simply select the event you want to test and click the Test button.


Using curl:

Curl is a great tool for interacting with APIs, among other functions. In this context, you can utilize curl to send HTTP requests to your API, mimicking the behavior of InsertSign's requests. You can find an example curl call for each individual webhook event on this page.

Retry attempts

If InsertSign does not receive a 200 response from a webhook server, we will NOT retry POSTing again.

Response codes

InsertSign uses standard HTTP response codes to indicate the success or failure of a request.

Codes in the 2xx range indicate success, codes in the 4xx range indicate an error given the information provided (e.g. a required parameter was omitted), and codes in the 5xx range indicate an error with the InsertSign service itself.


Parameter Description
200 OK - The request was successful.
400 Bad Request - The request could not be understood due to malformed syntax.
401 Unauthorized - Your API key is wrong or the access token has expired.
403 Limit Reached - Please make requests inactive, permanently delete requests to clear space, or upgrade your account.
404 Not Found - The requested resource is not found.
500 Internal Error - Our servers encountered an unexpected error while fetching or updating data to our database.
503 Service Unavailable - We’re temporarily offline. Please try again later.

Events

Request sent

Description:

Triggers when the status of a signature request changes from "draft" to "sent".


Sample Payload:

    {
      created_at: "2024-04-28T04:33:06.277Z",
      data: {
        request_id: "-N1hyGTaCNaIjJrkReq",
        account_id: "-Ne_JQph4vWOYBw03Co",
        request: {
          signers: {
            -NeD5nNcbr-nViVjjp: {
              id: "-NeD5nNcbr-nViVjjp",
              email: "example@gmail.com",
              name: "John Doe",
              label: "CEO"
            },
            -exampleJCDqrO1ZzuAPJCDW: {
              company: "Acme LLC",
              created_at: 1689893924614,
              id: "-exampleJCDqrO1ZzuAPJCDW",
              email: "jane.smith@gmail.com",
              name: "Jane Smith",
              timestamp: -1689893923878
            }
          },
          signer_order: ["-exampleJCDqrO1ZzuAPJCDW", "-NeD5nNcbr-nViVjjp"],
          progress: 0,
          sent_date: 1698640152432,
          status: "sent",
          title: "NDA for Acme",
          sender: {
            id: "1cnViVnv6W6Aqrkkm_x8",
            name: "John Doe",
            email: "john.doe@acme.com"
          }
        }
      },
      type: "request.sent"
    }

Payload Breakdown:

Property Name Type Description
created_at String The timestamp indicating when the event was created, formatted in ISO 8601.
data Object Contains the event data.
type String Type of event sent in the request body.
request Object Details about the request in context.
signers Object Details about all the signers, including name, email, and other information.
signers.label String The job title or role of the signer (e.g., "CEO").
signers.company String Signer's company or organization (e.g., "Acme Corporation"). Returns empty string, if no company name was provided.
signer_order Array The order of the signers in the request.
progress Number The progress of the signature request. Ranges 0 to 100 percent.
sent_date Number The timestamp of the request when it was first finalized and sent.
status String The current status of the request. See What do the Request statuses mean?
title String The name of the request.
sender Object The information of the user or member of your team that originally sent the request.
request_id String The unique identifier of the request.
account_id String The unique identifier of your InsertSign account.

Tip

The datetimes within webhook data will be long integers while the "created_at" key in the webhook request body is in ISO 8601 format.

The "signer_order" array may ONLY be present in this event.

Request completed

Description:

Triggers when all signers have signed the document and it's marked as 'complete'.


Sample Payload:

    {
      created_at: "2024-04-28T04:33:06.277Z",
      data: {
        request_id: "-N1hyGTaCNaIjJrkReq",
        account_id: "-Ne_JQph4vWOYBw03Co",
        request: {
          signers: {
            -NeD5nNcbr-nViVjjp: {
              id: "-NeD5nNcbr-nViVjjp",
              email: "example@gmail.com",
              name: "John Doe",
              status: "signed",
              type: "type_signer"
            }
          },
          progress: 100,
          sent_date: 1698640152432,
          status: "complete",
        title: "NDA for Acme",
        sender: {id: "1cnViVnv6W6Aqrkkm_x8",
          name: "John Doe",
          email: "john.doe@acme.com"
        }
        }
      },
      type: "request.completed"
    }

Payload Breakdown:

Property Name Type Description
created_at String The timestamp indicating when the event was created, formatted in ISO 8601.
data Object Contains the event data.
type String Type of event sent in the request body.
request Object Details about the request in context.
signers Object Details about all the signers, including name, email, and other information.
signers.label String The job title or role of the signer (e.g., "CEO").
signers.company String Signer's company or organization (e.g., "Acme Corporation"). Returns empty string, if no company name was provided.
progress Number The progress of the checklist. Ranges 0 to 100.
sent_date Number The timestamp of the request when it was first finalized and sent.
status String The current status of the request. See What do the Request statuses mean?
title String The name of the request.
sender Object The information of the user or member of your team that originally sent the request.
request_id String The unique identifier of the request.
account_id String The unique identifier of your InsertSign account.

Tip

The datetimes within webhook data will be long integers while the "created_at" key in the webhook request body is in ISO 8601 format.

Request archived

Description:

Triggers when the status of a request changes to "archived".


Sample Payload:

    {
      created_at: "2024-04-28T04:33:06.277Z",
      data: {
        request_id: "-N1hyGTaCNaIjJrkReq",
        account_id: "-Ne_JQph4vWOYBw03Co",
        request: {
          signers: {
            -NeD5nNcbr-nViVjjp: {
              id: "-NeD5nNcbr-nViVjjp",
              email: "example@gmail.com",
              name: "John Doe",
              label: "CEO"
            }
          },
          progress: 100,
          sent_date: 1698640152432,
          status: "archived",
          title: "NDA for Acme",
        sender: {id: "1cnViVnv6W6Aqrkkm_x8",
          name: "John Doe",
          email: "john.doe@acme.com"
        }
        }
      },
      type: "request.archived"
    }

Payload Breakdown:

Property Name Type Description
created_at String The timestamp indicating when the event was created, formatted in ISO 8601.
data Object Contains the event data.
type String Type of event sent in the request body.
request Object Details about the request in context.
signers Object Details about all the signers, including name, email, and other information.
signers.label String The job title or role of the signer (e.g., "CEO").
signers.company String Signer's company or organization (e.g., "Acme Corporation"). Returns empty string, if no company name was provided.
progress Number The progress of the checklist. Ranges 0 to 100.
sent_date Number The timestamp of the request when it was first finalized and sent.
status String The current status of the request. See What do the Request statuses mean?
title String The name of the request.
sender Object The information of the user or member of your team that originally sent the request.
request_id String The unique identifier of the request.
account_id String The unique identifier of your InsertSign account.

Tip

The datetimes within webhook data will be long integers while the "created_at" key in the webhook request body is in ISO 8601 format.

Note: This webhook may trigger more than once and whenever the status changes to "archived".

Request deleted

Description:

Triggers when the request is deleted.


Sample Payload:

    {
      created_at: "2024-04-28T04:33:06.277Z",
      data: {
        request_id: "-N1hyGTaCNaIjJrkReq",
        account_id: "-Ne_JQph4vWOYBw03Co",
        request: {
          signers: {
            -NeD5nNcbr-nViVjjp: {
              id: "-NeD5nNcbr-nViVjjp",
              email: "example@gmail.com",
              name: "John Doe"
            }
          },
          progress: 100,
          sent_date: 1698640152432,
          status: "archived",
          title: "NDA for Acme",
        sender: {id: "1cnViVnv6W6Aqrkkm_x8",
          name: "John Doe",
          email: "john.doe@acme.com"
        }
        }
      },
      type: "request.deleted"
    }

Payload Breakdown:

Property Name Type Description
created_at String The timestamp indicating when the event was created, formatted in ISO 8601.
data Object Contains the event data.
type String Type of event sent in the request body.
request Object Details about the request in context.
signers Object Details about all the signers, including name, email, and other information.
signers.label String The job title or role of the signer (e.g., "CEO").
signers.company String Signer's company or organization (e.g., "Acme Corporation"). Returns empty string, if no company name was provided.
progress Number The progress of the checklist. Ranges 0 to 100.
sent_date Number The timestamp of the request when it was first finalized and sent.
status String The current status of the request. See What do the Request statuses mean?
title String The name of the request.
sender Object The information of the user or member of your team that originally sent the request.
request_id String The unique identifier of the request.
account_id String The unique identifier of your InsertSign account.

Tip

The datetimes within webhook data will be long integers while the "created_at" key in the webhook request body is in ISO 8601 format.

Note: Contains data of the request as it was BEFORE it is deleted.

Contact created

Description:

Triggers when a new recipient is added (created) in InsertSign.


Sample Payload:

    {
      created_at: "2024-04-28T04:33:06.277Z",
      data: {
        email: "example@gmail.com",
      name: "John Doe",
      label: "CEO",
      company: "Acme",
      id: "-NeD5nNcbr-nViVjjp",
      account_id: "-Ne_JQph4vWOYBw03Co",
      created_at: 1712595976304
      },
      type: "contact.created"
    }

Payload Breakdown:

Property Name Type Description
data Object Contains the event data.
type String Type of event sent in the request body.
name String The name of the contact (e.g., "John Doe").
email String The email address associated with the contact (e.g., "example@email.com").
label String The job title or role of the contact (e.g., "CEO").
company String Contact's company or organization (e.g., "Acme Corporation"). Returns empty string, if no company name was provided.
created_at Number The timestamp indicating the date and time when the record was created (e.g., 1690300434633).
id String A unique identifier for the recipient added (e.g., "-NlybKR3qJYCzp_x7y-3").
account_id String The unique identifier of your InsertSign account (e.g., "example1aCN3qJCDWuAPWdbK23_Company").

Tip

The datetimes within webhook data will be long integers while the "created_at" key in the webhook request body is in ISO 8601 format.

Signer signed

Description:

Triggers when a signer signs a request.


Sample Payload:

    {
      created_at: "2024-04-28T04:33:06.277Z",
      data: {
        email: "example@gmail.com",
        name: "John Doe",
        type: "signer", // signer or sender
        device: "desktop",
        ip: "127.0.0.1",
        signed_at: 1712595976304,
        request_id: "-N1hyGTaCNaIjJrkReq",
        id: "-NeD5nNcbr-nViVjjp",
        account_id: "-Ne_JQph4vWOYBw03Co"
      },
      type: "signer.signed"
    }

Payload Breakdown:

Property Name Type Description
data Object Contains the event data.
type String Type of event sent in the request body.
name String The name of the signer (e.g., "John Doe").
email String The email address associated with the signer (e.g., "example@email.com").
signers.type String Type of signer. Possible values: "signer", "sender".
device String The device used to sign the request. Possible values: "desktop", "mobile", "tablet".
ip String The IP address of the device used to sign the request.
signed_at Number The timestamp indicating when the signer signed the request (e.g., 1712595976304).
request_id String The document ID of the signature request in context.
id String A unique identifier for the signer (e.g., "-NlybKR3qJYCzp_x7y-3").
account_id String The unique identifier of your InsertSign account (e.g., "example1aCN3qJCDWuAPWdbK23_Company").

Tip

The datetimes within webhook data will be long integers while the "created_at" key in the webhook request body is in ISO 8601 format.

Email delivered

Description:

Triggers whenever an email is successfully delivered to a participant's inbox.


Sample Payload:

    {
      created_at: "2024-04-28T04:33:06.277Z",
      data: {
        subject: "NDA for Acme - Signature requested by John Doe",
        to: "example@gmail.com",
        request_id: "-N1hyGTaCNaIjJrkReq",
        account_id: "-Ne_JQph4vWOYBw03Co"
      },
      type: "email.delivered"
    }

Payload Breakdown:

Property Name Type Description
created_at String The timestamp indicating when the event was created, formatted in ISO 8601.
data Object Contains the event data.
type String Type of event sent in the request body.
subject String Contains the subject of the email sent.
to String The email of the recipient.
request_id String The unique identifier of the request in context.
account_id String The unique identifier of your InsertSign account (e.g., "example1aCN3qJCDWuAPWdbK23_Company").

Tip

The datetimes within webhook data will be long integers while the "created_at" key in the webhook request body is in ISO 8601 format.

"Participants" includes signers, senders, and CC recipients.

Email bounced

Description:

Triggers whenever an email fails to be delivered due to bounces.


Sample Payload:

    {
      created_at: "2024-04-28T04:33:06.277Z",
      data: {
        subject: "Overdue: information request for Approval Questionnaire",
        to: "example@gmail.com",
        request_id: "-N1hyGTaCNaIjJrkReq",
        account_id: "-Ne_JQph4vWOYBw03Co"
      },
      type: "email.bounced"
    }

Payload Breakdown:

Property Name Type Description
created_at String The timestamp indicating when the event was created, formatted in ISO 8601.
data Object Contains the event data.
type String Type of event sent in the request body.
subject String Contains the subject of the email that bounced.
to String The email of the recipient.
request_id String The unique identifier of the request in context.
account_id String The unique identifier of your InsertSign account (e.g., "example1aCN3qJCDWuAPWdbK23_Company").

Tip

The datetimes within webhook data will be long integers while the "created_at" key in the webhook request body is in ISO 8601 format.

Note: Please re-check and enter valid email address.

Email spammed

Description:

Triggers if the recipient clicks "Mark as Spam" from their inbox.


Sample Payload:

    {
      created_at: "2024-04-28T04:33:06.277Z",
      data: {
        subject: "NDA for Acme - Signature requested by John Doe",
        to: "example@gmail.com",
        request_id: "-N1hyGTaCNaIjJrkReq",
        account_id: "-Ne_JQph4vWOYBw03Co"
      },
      type: "email.spammed"
    }

Payload Breakdown:

Property Name Type Description
created_at String The timestamp indicating when the event was created, formatted in ISO 8601.
data Object Contains the event data.
type String Type of event sent in the request body.
subject String Contains the subject of the email that was marked as spam.
to String The email address of the recipient.
request_id String The unique identifier of the request in context.
account_id String The unique identifier of your InsertSign account (e.g., "example1aCN3qJCDWuAPWdbK23_Company").

Tip

The datetimes within webhook data will be long integers while the "created_at" key in the webhook request body is in ISO 8601 format.

Note: Spam complaints are usually generated when a recipient is NOT expecting an email. Please reach out to the signer/recipient.