Webhooks allow you to receive real-time updates about the status of your envelopes in the Sign.Plus. This article will walk you through the process of setting up and handling webhooks for your Sign.Plus integration.
Step 1: Create a webhook
To start receiving real-time updates, you first need to create a webhook in the Sign.Plus. Here's how:
- Decide on a target URL where you want to receive webhook notifications. This should be an endpoint on your server that's set up to handle incoming POST requests.
- Choose the event(s) you want to track. Sign.Plus offers the following webhook events:
-
envelope_completed
- When an envelope is completed -
envelope_expired
- When an envelope is expired -
envelope_declined
- When an envelope is declined -
envelope_voided
- When an envelope is voided
-
- Use the Sign.Plus API to create the webhook. You'll need to specify your target URL and the event(s) you want to track.
For detailed information on how to create a webhook using the Sign.Plus API, refer to the Create a webhook endpoint documentation.
Step 2: Handle webhook notfications
Once you've set up your webhook, Sign.Plus will send POST requests to your specified URL whenever the tracked events occur. Here's what you need to know about handling these notifications:
-
Request Method: All webhook notifications are sent as HTTP
POST
requests. -
Payload Structure: The webhook payload is a JSON object containing two main sections:
-
hook
: Contains metadata about the webhook itself. -
data
: Contains information about the envelope that triggered the event.
-
-
Payload Examples: Here are examples of payloads for different events:
// ENVELOPE_DECLINED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_declined",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
// ENVELOPE_COMPLETED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_completed",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
// ENVELOPE_EXPIRED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_expired",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
// ENVELOPE_VOIDED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_voided",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
} -
Handling the Notification: When your server receives a webhook notification:
- Verify the payload to ensure it's a valid webhook notification.
- Extract the relevant information from the payload.
- Perform any necessary actions based on the event type (e.g., update your database, notify users, trigger other processes).
- Send a
200 OK
response to acknowledge receipt of the webhook.
Best practices
- Security: Ensure your webhook endpoint is secure. Consider implementing authentication for your webhook URL.
- Idempotency: Design your webhook handler to be idempotent. This means it should produce the same result even if the same webhook is received multiple times.
- Error Handling: Implement robust error handling in your webhook processing logic.
By following this guide, you'll be able to set up and handle webhooks effectively, allowing your application to receive real-time updates about envelope statuses in the Sign.Plus.