> For the complete documentation index, see [llms.txt](https://fuseworks.gitbook.io/fusesign/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fuseworks.gitbook.io/fusesign/deep-dives/webhooks.md).

# Webhooks

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 [Bundle](/fusesign/api-references/bundle.md#api-bundle-create) specify `Settings` > `WebhookUrl` in the payload:

```json
{
  "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": "+61411111111"
      }
    }
  ],
  "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 :)