Webhooks

Overview

Ironclad offers multiple event types when setting up a webhook. This allows for more granular control on the types of events you need to receive. We recommend only choosing the events you absolutely need to reduce the volume on your webhook intake service. Webhooks allow you to specify that we should POST to your URL when certain events happen. The POST body will include webhook details and a payload specific to the webhook type.

Each webhook target URL can only be registered once, with a list of the events it will listen for. If you need to modify a webhook, you can delete and re-create it.

Retries

Ironclad will retry webhooks for up to three days in the event of an error response.

Ironclad will attempt to send the POST request, and assume failure if we get a 4xx or 5xx response. If a webhook gets a 410 response, it will delete itself and not fire again. If the response is any other 4xx or 5xx code, it will retry the webhook. A total of up to twelve retries will be attempted over three days; the time between retries is determined by an exponential backoff function using a waiting time of sixty seconds and a base factor of two.

Event Types

workflow_launched

The workflow_launched webhook event type is triggered each time a workflow is launched. This event is especially helpful when you're launching workflows asynchronously.

Example payload:

{
  "companyID": "605b9829cdd37d296123f4b4",
  "payload": {
    "event": "workflow_launched",
    "templateID": "6063ac9e01a5542dafa3722b",
    "workflowID": "611fbd699f4a33b41d9f8295"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "611fb96cb670f852d58db210"
}

workflow_updated

The workflow_updated event is triggered each time a workflow has been updated. This can encompass many actions on a workflow (i.e. comments, editing comments, adjustments to the launched workflow, etc.).

Example payload:

{
  "companyID": "605b9829cdd37d296123f4b4",
  "payload": {
    "event": "workflow_updated",
    "templateID": "6063ac9e01a5542dafa3722b",
    "workflowID": "611fbd699f4a33b41d9f8295"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "611fb96cb670f852d58db210"
}

workflow_completed

The workflow_completed event is triggered once the workflow has been completed.

Example payload:

{
  "companyID": "605b9829cdd37d296123f4a4",
  "payload": {
    "event": "workflow_completed",
    "recordIDs": ["fb215e19-6d32-4d76-b457-0a69450b3964"],
    "templateID": "6063ac9e01a5542dafa3722b",
    "workflowID": "611fbd699f4a33b41d9f8295"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "611fb96cb670f852d58db210"
}

workflow_cancelled

The workflow_cancelled event is triggered any time the workflow is canceled.

Example payload:

{
  "companyID": "605b9829cdd37d296123f4b4",
  "payload": {
    "event": "workflow_cancelled",
    "templateID": "60e5d91d93bcd5f8da474be0",
    "workflowID": "611fb9dd43d439578a790c6a"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "611fb96cb670f852d58db210"
}

workflow_approval_status_changed

The workflow_approval_status_changed event is triggered when an approver approves a workflow.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "approvalID": "approvere45f64a2582548299b7d82855e8283a0",
    "approvalName": "VP of Approvals",
    "event": "workflow_approval_status_changed",
    "status": "approved",
    "userEmail": "[email protected]",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_attribute_updated

The workflow_attribute_updated event is triggered when workflow attributes, such as counterparty signer names, are modified.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "changedAttributes": [
      "counterpartyName",
      "rolec5c07217115e43c1947e9504835a8d5c",
      "draft"
    ],
    "event": "workflow_attribute_updated",
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_comment_added

The workflow_comment_added event is triggered when a new comment is added to the workflow. This includes any comment event, including when a document is added to the workflow and a comment item is added.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "commentID": "n62iak877",
    "event": "workflow_comment_added",
    "isExternal": true,
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_comment_removed

The workflow_comment_removed event is triggered when a comment is deleted.

Example payload:

{
    "companyID": "6193fdf218328854844f18a0",
    "payload": {
        "commentID": "n62iak877",
        "event": "workflow_comment_removed",
        "isExternal": false,
        "templateID": "6247777a8ef13520f19f2406",
        "userID": "605b985b886edf1f82bec9b0",
        "workflowID": "619581f0110ff070d0aadb12"
    },
    "timestamp": "2022-04-07T21:36:52.776Z",
    "webhookID": "619581d6110ff070d0aad9a1"
    }
}

workflow_comment_updated

The workflow_comment_updated event is triggered when a comment is edited.

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "commentID": "n62iak877",
    "event": "workflow_comment_updated",
    "isExternal": false,
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_comment_reaction_added

The workflow_comment_reaction_added event is triggered when an emoji reaction is added to a comment.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "commentID": "n62iak877",
    "emojiID": "grinning",
    "event": "workflow_comment_reaction_added",
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_comment_reaction_removed

The workflow_comment_reaction_removed event is triggered when an emoji reaction is removed from a comment.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "commentID": "n62iak877",
    "emojiID": "grinning",
    "event": "workflow_comment_reaction_removed",
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_counterparty_invite_sent

The workflow_counterparty_invite_sent event is triggered when a user sends an invite to collaborate to a counterparty.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "event": "workflow_counterparty_invite_sent",
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_counterparty_invite_revoked

The workflow_counterparty_invite_revoked event is triggered when a collaboration invite to the counterparty is revoked.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "counterpartyID": "605b985b886edf1f82bec9b0",
    "event": "workflow_counterparty_invite_revoked",
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_documents_added

The workflow_documents_added event is triggered when documents are added to the workflow. If multiple documents are added in the same instance, the webhook will only fire once and contain document keys of all added documents.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "documentKeys": ["Bh1VrsMweL3", "iT850xWEKL5"],
    "event": "workflow_documents_added",
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_documents_removed

The workflow_documents_removed event is triggered when documents are removed from the workflow. If multiple documents are removed in the same instance, the webhook will only fire once and contain document keys of all removed documents.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "documentKeys": ["Bh1VrsMweL3", "iT850xWEKL5"],
    "event": "workflow_documents_removed",
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_documents_updated

The workflow_documents_updated event is triggered when documents are updated. If multiple documents are updated in the same instance, the webhook will only fire once and contain document keys of all updated documents.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "documentKeys": ["Bh1VrsMweL3", "iT850xWEKL5"],
    "event": "workflow_documents_updated",
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_documents_renamed

The workflow_documents_renamed event is triggered when documents are renamed. If multiple documents are renamed in the same instance, the webhook will only fire once and contain document keys of all renamed documents.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "documentKeys": ["Bh1VrsMweL3", "iT850xWEKL5"],
    "event": "workflow_documents_renamed",
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_document_edited

The workflow_document_edited event is triggered when a document is edited within the Ironclad editor.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "documentKey": "Bh1VrsMweL3",
    "event": "workflow_document_edited",
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec**9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_changed_turn

The workflow_changed_turn event is triggered at the start of any turn on a workflow. This includes the first turn on a workflow, turn changes from one party to another, and other events, such as unpausing a workflow, that resume a turn.

Example payload:

{
    "companyID": "605b9829cdd37d296123f4b4",
    "payload": {
        "event": "workflow_changed_turn",
        "templateID": "6063ac9e01a5542dafa3722b",
        "workflowID": "611fbd699f4a33b41d9f8295",
        "fromParty": "internal",
        "toParty": "counterparty"
    },
    "timestamp": "2022-04-07T21:36:52.776Z",
    "webhookID": "611fb96cb670f852d58db210"
}

📘

Note on fromParty in payload:

The fromParty is omitted in the first turn or in the event that we resume a turn, and that the toParty is always included.

workflow_paused

The workflow_paused event is triggered when a workflow is paused.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "event": "workflow_paused",
    "templateID": "6247777a8ef13520f19f2406",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_resumed

The workflow_resumed event is triggered when a workflow is resumed.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "event": "workflow_resumed",
    "templateID": "6247777a8ef13520f19f2406",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_roles_assigned

The workflow_roles_assigned event is triggered when a role is assigned in a workflow. (e.g. when a new user is assigned to an approval group.)

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "event": "workflow_roles_assigned",
    "templateID": "6247777a8ef13520f19f2406",
    "workflowID": "619581f0110ff070d0aadb12",
    "userId": "605b985b886edf1f82bec9b0",
    "RoleAssignments" [
      {
        "action": "assigned",
        "assigneeID": "62d05b12b0d28dbf30e5f10a",
        "roleID": "approver32b4b485c9374855bcdb8a3580c13bab"
      },
      {
        "action": "assigned",
        "assigneeID": "605b985b886edf1f82bec9b0",
        "roleID": "owner"
      }
    ]
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_signature_packet_sent

The workflow_signature_packet_sent event is triggered when a signature packet is sent out for review.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "event": "workflow_signature_packet_sent",
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_signature_packet_uploaded

The workflow_signature_packet_uploaded event is triggered when a signature packet is uploaded to the workflow from the signature collection modal or from an attachment sent to the activity feed. The event is triggered whether a partially-signed or fully-signed signature packet is uploaded.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "event": "workflow_signature_packet_uploaded",
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_signature_packet_signatures_collected

The workflow_signature_packet_signatures_collected event is triggered when (1) each signer signs an eSignature request from Ironclad or (2) an Ironclad user manually uploads a signature packet during the sign step and indicates it is (a) partially-signed or (b) fully-signed.

The signatures property identifies the signatures that were collected; signatures from preceding signers are omitted (see the List all Workflow Signers endpoint if you need to retrieve the state of all signers). If a user uploads a signature packet (e.g., documents ink signed offline), the user will specify which signatures are included in the uploaded document. In that scenario, one webhook will be sent and the signatures property will list the signatures specified by the user.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "event": "workflow_signature_packet_signatures_collected",
    "templateID": "6247777a8ef13520f19f2406",
    "workflowID": "619581f0110ff070d0aadb12",
    "signatures": [
      {
        "name": "Alex Fleming",
        "email": "[email protected]",
        "roleName": "Counterparty Signer"
      },
      {
        "name": "Calvin Hobbes",
        "email": "[email protected]",
        "roleName": "Acme Inc. Signer"
      }
    ]
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_signature_packet_fully_signed

The workflow_signature_packet_fully_signed event is triggered when (1) an eSignature request has been fully signed or (2) an Ironclad user manually uploads a signature packet and indicates it is fully signed.

Note: For manually uploaded signature packets, Ironclad relies on the user specifying that the signature packet is fully signed; Ironclad does not validate that the uploaded document contains the correct signatures.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "event": "workflow_signature_packet_fully_signed",
    "templateID": "6247777a8ef13520f19f2406",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_signature_packet_cancelled

The workflow_signature_packet_cancelled event is triggered when the request for a signature is cancelled.

Example payload:

{
  "companyID": "6193fdf218328854844f18a0",
  "payload": {
    "event": "workflow_signature_packet_cancelled",
    "templateID": "6247777a8ef13520f19f2406",
    "userID": "605b985b886edf1f82bec9b0",
    "workflowID": "619581f0110ff070d0aadb12"
  },
  "timestamp": "2022-04-07T21:36:52.776Z",
  "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_signer_added

The workflow_signer_added event is triggered when a signer is added to a workflow.

Example payload:

{
    "companyID": "6193fdf218328854844f18a0",
    "payload": {
        "event": "workflow_signer_added",
        "templateID": "6247777a8ef13520f19f2406",
        "userID": "605b985b886edf1f82bec9b0",
        "workflowID": "619581f0110ff070d0aadb12"
    },
    "timestamp": "2022-04-07T21:36:52.776Z",
    "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_signer_removed

The workflow_signer_removed event is triggered when a signer is removed from a workflow.

Example payload:

{
    "companyID": "6193fdf218328854844f18a0",
    "payload": {
        "event": "workflow_signer_removed",
        "templateID": "6247777a8ef13520f19f2406",
        "userID": "605b985b886edf1f82bec9b0",
        "workflowID": "619581f0110ff070d0aadb12"
    },
    "timestamp": "2022-04-07T21:36:52.776Z",
    "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_signer_reassigned

The workflow_signer_reassigned event is triggered when a signer is reassigned on a workflow.

Example payload:

{
    "companyID": "6193fdf218328854844f18a0",
    "payload": {
        "event": "workflow_signer_reassigned",
        "templateID": "6247777a8ef13520f19f2406",
        "userID": "605b985b886edf1f82bec9b0",
        "workflowID": "619581f0110ff070d0aadb12"
    },
    "timestamp": "2022-04-07T21:36:52.776Z",
    "webhookID": "619581d6110ff070d0aad9a1"
}

workflow_step_updated

The workflow_step_updated event is triggered when a workflow transitions between the four steps of a workflow (Create, Review, Sign, and Archive). The possible transitionvalues in order of occurrence are below:

TransitionNotes
create_to_reviewWorkflows move from create to review when all workflow launch forms have been submitted (launch form and any additional internal or counterparty forms).

A webhook is still dispatched if the review step is "skipped" (i.e. no approvers triggered).
review_to_signA webhook is dispatched even if the review step is "skipped" (i.e. no reviews triggered)
revert_sign_to_reviewA webhook that is sent when a user moves a workflow from the sign step back to the review step.
sign_to_archiveA webhook that is sent when the archive step is reached (including if auto-archive is enabled).
revert_archive_to_signA webhook that is sent when a user moves a workflow from the archive step back to the sign step.

For events that occur outside of or within the four workflow steps, consider listening for other webhooks. Webhooks such as workflow_launched, workflow_completed, workflow_approval_status_changed, etc. are available for other workflow events.

Example payload:

{
    "companyID": "6193fdf218328854844f18a0",
    "payload": {
        "event": "workflow_step_updated",
        "templateID": "6247777a8ef13520f19f2406",
        "transition": "review_to_sign",
        "workflowID": "619581f0110ff070d0aadb12"
    },
    "timestamp": "2022-04-07T21:36:52.776Z",
    "webhookID": "619581d6110ff070d0aad9a1"
}

* (all events)

This webhook event will be triggered for all events listed above.