Webhooks
DottedSign API offers webhooks as a powerful tool for event-driven integration with your application. By subscribing to specific events, your application can receive real-time HTTP POST payloads at your configured webhook URL. This feature enables seamless updates to internal or external systems, initiates custom workflows, and facilitates synchronization with third-party applications. Utilize webhooks to manage events in your integrations effectively and efficiently.
Setup
When creating an application, users can set up a webhook URL. For guidance on this process, refer to the Create An Application section.
Payload
| Parameter | Nullable | Description |
|---|---|---|
resource_id | X | Resource ID. |
resource_type | X | Resource type, e.g., task. |
action_name | X | Event name. See Event Table for all events. |
event_datetime | X | Event occurred timestamp. |
event_email | X | The member who triggered the event. |
ip_address | X | IP address at which the event occurred. |
user_agent | X | The user agent or device at which the event occurred. |
task | O | Task details (if the resource_type is task). |
Signature
To enhance security and prevent spoofing, DottedSign Webhook adds a Signature header. This signature, generated by encoding the JSON payload with the application’s client secret using sha256 algorithm, helps verify the authenticity of the webhook. Application developers can validate this header to confirm the webhook is sent by the DottedSign API.
Event Table
DottedSign API currently supports several events, as detailed below.
| Event | Resource Type | Description |
|---|---|---|
created | task | Task has been created. |
sent | task | Task has been sent to signers. |
modified | task | Task has been updated by the owner. |
signed | task | Task has been signed by one signer. |
completed | task | Task has been signed completely by all signers. |
declined | task | Task has been declined by a signer. |
voided | task | Task has been voided by the owner. |
expired | task | Task has exceeded the deadline. |
archived | task | Task has been archived by a member with permission. |
unarchived | task | Task has been unarchived by a member with permission. |
discarded | task | Task has been discarded to the trash can by the owner or the one with permission. |
restored | task | Task has been restored from the trash can by the owner or the one with permission. |
garbage_collected | task | Task can be completely deleted can not be restored anymore by the system. |
signer_changed | task | The signer of the task has been changed by the owner or the original signer. |
Retry Policy
DottedSign API automatically retries when a webhook receiver responds with a non-2xx HTTP status code (e.g. 3xx, 4xx, 5xx). The retries follow an exponential backoff algorithm, gradually increasing the interval between attempts.
Webhook Retry Table
| Retry Attempt | Retry Interval (Minutes) | Retry Behavior |
|---|---|---|
| 1 | 1 | After first attempt fails |
| 2 | 2 | After first retry fails |
| 3 | 3 | After second retry fails |
Notice
If 10 webhook delivery failures occur in a single day, the system will temporarily suspend the application's webhook delivery until the user re-examines and reactivates the settings.
Webhook Log
DottedSign API logs each webhook delivery, providing a record for user review and verification.
Updated 6 months ago