Integrating your own email or SMS provider

Don't want to use our emails or SMS messages? Simply set up a new integration to configure using your own.

In this article we'll share how to set up integrations to your own SMS and email providers. You'll learn how to:

  1. Catch a "Request Sent" webhook when a signature request is sent to your signer.
  2. Learn how to process the webhook in order to include the right information in your email or SMS message.

What you'll need to get started

To get started with this guide, you'll need the following:

  • API access
  • Access and knowledge on setting up Webhooks
  • A service or functioning endpoint for Ironclad Clickwrap Webhooks to reach out to (AWS' Lambda is great for things like this)

Primary data flows for integration

There are three primary data flows to consider when building your own integration to an email or SMS provider:

  1. Catch a webhook when signature requests are sent to your signer
  2. Catch a webhook when a signature request is signed by a signer
  3. Catch a webhook when a signature request is completed by all parties

📘

Note: Reminders aren't scoped for this integration

PactSafe sends reminders when a signer hasn't signed after 3, 7, and 14 days. If you'd like to setup reminders, you'll also want to set up a recurring job that uses these reminders. Currently, there is no "Request Reminder" webhook but this is something we'll consider for the roadmap.

Getting started

You'll first want to set up a webhook with 3 events enabled: "Request Sent", "Request Signed", and "Request Complete". Click here to go to your Integrations, add a "Webhook", and follow the instructions here for more detail.

Next, you will want to build a dedicated service to catch webhooks fired by PactSafe in your own service and then handle accordingly.

🚧

Note: What if the webhooks fails to reach my own web service?

Failed webhook events will retry on a regular cadence for up to 24 hours should any failures occur.

1. Catch a webhook when signature requests are sent to your signer

If you're using the REST API to process signature requests in PactSafe, you're likely calling a POST to /requests/:request_id/send to deliver the finalized signature request to your signer(s). Upon doing this, PactSafe will trigger a webhook called "Request Sent" to any webhooks currently configured on the account.

Below are the 4 steps to your integration to deliver the SMS or email from your own provider.

Step

Description

  1. Catch "Request Sent" webhook

An example of this webhook can be found here.

  1. Make HTTP GET request

The below properties within the request are what you'll need for the next step:

GET => /v1.1/requests/:request_id

{
  "signers": [
    {
      "send_to": {
          "email": true,
          "mobile_number": true
      },
      "signer": {
        "email": "[email protected]",
        "mobile_number": "+13175551234"
      }
      "request_url": "..."
  ]
}
  1. Shorten Signing URL

Next, you can take the signing URL (the request_url property) for your signer and shorten it using an API like Bit.ly or Rebrandly.

  1. Send SMS or email

Once you've shortened the link, you can trigger the email or SMS to your own provider passing in the mobile number or email address, signing URL, and other metadata that you may want to leverage from PactSafe.

Example SMS:
You've been sent "PS Employment Agreement" by PactSafe. Please review & sign: https://bit.ly/2131NDa

2. Catch a webhook when signature requests are signed by one of your signers

If you have more than one signer, you'll want to keep track of inidividual signers completing as they sign. PactSafe will trigger a webhook called "Request Signed" to any webhooks currently configured on the account every time any signer signs a signature request.

📘

Note: If you only have one signer

If you only have one signer on your signature request, PactSafe will send both a "Request Signed" and "Request Complete" (asynchronously, so not necessarily in order) for the final signature on the signature request.

Below are the steps to follow when a signature request is signed.

Step

Description

1. Catch "Request Signed" webhook

An example of this webhook can be found here.

2. Make HTTP GET request

The below properties within the request are what you'll need for the next step:

GET => /v1.1/requests/:request_id

{
  "signers": [
    {
      "send_to": {
          "email": true,
          "mobile_number": true
      },
      "signer": {
        "email": "[email protected]",
        "mobile_number": "+13175551234"
      }
      "request_url": "..."
  ]
}

3. Send SMS or email

You can update signers via email or SMS that others have signed the request or update the status in your system.

Example SMS:
Eric Smith has signed "Employment Agreement". One more signature is needed to complete the document.

2. Catch a webhook when signature requests are completed by all signers

When the signature request is complete, you'll want to notify all signers via email or SMS with a link to review and download the signature request PDF. PactSafe will trigger a webhook called "Request Complete" to any webhooks currently configured on the account every time a signature request is completed.

Below are the steps to follow when a signature request is completed:

Step

Description

1. Catch "Request Completed" webhook

An example of this webhook can be found here.

2. Make HTTP GET request

The below properties within the request are what you'll need for the next step:

GET => /v1.1/requests/:request_id

{
  "signers": [
    {
      "send_to": {
          "email": true,
          "mobile_number": true
      },
      "signer": {
        "email": "[email protected]",
        "mobile_number": "+13175551234"
      }
      "request_url": "..."
  ]
}

3. Shorten Signing URL

Next, you can take the signing URL (the request_url property) for your signer and shorten it using an API like Bit.ly or Rebrandly.

4. Send SMS or email

Once you've shortened the link for each signer that's on the signature request, you can loop through each signer and trigger the email or SMS through your own provider passing in the mobile number or email address, shortened signing URL, and other metadata that you may want to leverage from PactSafe.

Example SMS:
"PS Employment Agreement" has been accepted by all parties. Download your document here: https://bit.ly/2131NDa


Did this page help you?