Webhooks

FuseSign webhooks provide real-time, event-based updates with secure payloads, authentication, and automatic retries for reliability.

Webhooks are advantageous for their ability to facilitate real-time communication between applications:

• Instant Notifications: Webhooks allow your application to receive real-time data updates without polling the server repeatedly. This ensures timely updates.

• Resource Efficiency: Unlike traditional APIs that require constant checking for updates, webhooks only send data when an event occurs, reducing resource consumption.

• Automated Workflows: By triggering specific actions based on events, webhooks enable seamless integration between systems, allowing for automated workflows and enhanced productivity.

• Scalability: As your application grows, webhooks can efficiently handle increased event loads, ensuring consistent performance and user experience.

Webhook Structure

The webhook event structure is of type TransactionalBundleWebhookPayload:

{
    "WebhookId":"dd7be5ec-1560-49b1-a1a7-02be393dc7fe",  // Webhook event identifier
    "BundleId":"69d3400e-1af1-44c7-9315-b80dd6e1e798",   // The bundle for the webhook
    "EventType":"CustomerDocumentSigned",                // Bundle event type
    "BundleHistoryEvent": {                                // Bundle history event details
        "Id":"cc0c0745-7ba1-4134-b946-674d78c98fef",
        "DateTime":"2020-09-14T03:54:07.2844251Z",
        "BundleId":"69d3400e-1af1-44c7-9315-b80dd6e1e798",
        "DocumentId":"5ec03200-1db1-40ec-a553-95b55e30bacc",
        "CustomerId":"a960f86a-e9ba-49c8-ae1c-646a4ec76ac5",
        "Action":"CustomerDocumentSigned",
        "ActionNotes":"Document Signed: test doc",
        "IP":"61.68.36.158"
    },
    "ActionDescription":"Document Signed: test doc",     // Textual Description
    "TenantId":"7ffcbae4-9f50-4136-8de6-edb6f796dc3f"    // TenantId of the bundle
}

Webhook Events List

Event	Description
BundleArchived	Bundle has been archived
BundleArchiveWarning	Bundle will be archived after 7 days
BundleClosureRegistered	Bundle has registered a closure event. This means the bundle can be archived safely
BundleCreated	Bundle has been committed and is ready to send to customers
BundleDocumentDownloaded	Bundle document downloaded
BundleError	Bundle signing has encountered an error (need to contact FuseSign support)
BundleFinalised	Bundle has been finalised (all documents signed)
BundleRetracted	Bundle has been retracted
CustomerActionsCompleted	Customer actions completed for a bundle
CustomerBundleOpened	Customer has opened the bundle link
CustomerBundleRejected	Customer has rejected an entire bundle
CustomerDocumentRejected	Customer has rejected a document
CustomerDocumentSigned	Customer has signed a document
CustomerEmailDelivered	Email successfully delivered to customer
CustomerEmailDeliveredWithOOTO	The message was successfully delivered but the recipient's mailbox auto-replied with an 'out of the office' message
CustomerEmailFailure	Email failed to deliver to customer
CustomerEmailOpened	Customer opened Email
CustomerRequestedNewLink	Customer has requested a new signing link (due to expiry)
DocumentFinalised	The document has been digitally signed and is ready for download
DraftBundleDeleted	Draft bundle has been deleted
WebhookURLChanged	Bundle webhook URL updated

Webhook Setup

When a bundle is created via #api-bundle-create specify Settings > WebhookUrl in the payload:

{
  "Subject": "This is the subject field in the email",
  "Body": "Hello Signer, Could you please sign please",
  "CreateMode": "CreateAndSend",
  "Customers": [
    {
      "Customer": {
        "Name": "MY NAME HERE",
        "Email": "MY EMAIL HERE",
        "PhoneNumber": "[phone]"
      }
    }
  ],
  "Documents": [
    {
      "DisplayName": "Name of Document",
      "DocumentUrl": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
      "DocumentOrder": 0,
      "CustomerSigners": [
        0
      ]
    }
  ],
  "ViewMode": "SmsToSign",
  "Settings": {
    "WebhookUrl": "https://example.com/my_fusesign_webhookID"
  }
}

Webhook authentication

All webhooks will be sent with your developer specific Fuse-Signature header. This header can be used to verify the message was sent via the FuseSign API. The header can be found on your developer listing page.

Webhook retry logic

FuseSign webhook's will automatically retry if no 200 response is received. The system will retry up to 5 times with the following back-off logic: • 1st retry – after 30 minutes • 2nd retry – 60 minutes thereafter • 3rd retry – 120 minutes thereafter • 4th retry – 120 minutes thereafter • 5th and final retry – 120 minutes thereafter

If the 5th and final retry is unsuccessful, a permanent webhook failure is registered in our system – if these are frequent, we’ll get in touch :)