> ## Documentation Index
> Fetch the complete documentation index at: https://developer.fabric.inc/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook Settings
fabric allows you to configure preset webhooks to listen for key events and review webhook history.
## Supported Webhooks
The following webhooks are available in the **Topic** field when selecting a webhook.
| Webhook Topic | Description | Recommended |
| :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- |
| **Brand Completed Onboarding** | Triggers when a supplier finishes their onboarding process. | Recommended |
| **Brand Location Created** | Triggers when a supplier adds a new warehouse location in fabric. | Optional |
| **Brand Location Deleted** | Triggers when a supplier removes a warehouse location from fabric. | Optional |
| **Brand Location Updated** | Triggers when a supplier updates details for a warehouse location in fabric. | Optional |
| **Connection Created** | Triggers when a supplier accepts a merchant's invitation, creating a connection with the merchant's default settings. | Recommended |
| **Credit Memo Created** | Triggers when a credit memo is created in fabric. | Optional |
| **Feed Request Approved** | Triggers when a supplier approves an Import Request. | Optional - Recommended if the merchant uses "Import Requests" for merchandising. |
| **Feed Request Reviewed** | Triggers when a supplier reviews an Import Request. | Optional - Recommended if the merchant uses "Import Requests" for merchandising. |
| **Invoice Created** | Triggers when a supplier creates an invoice in fabric. | Recommended |
| **Item Inventory Updated** | Triggers when a supplier updates inventory levels for an item. | Recommended |
| **Offer Created** | Triggers when an offer is created in fabric. | Optional |
| **Order Backorder Date Updated** | Triggers when a supplier updates the backorder date for an item on an order in fabric. | Optional - Recommended if the merchant allows suppliers to backorder items on orders. |
| **Order Backordered** | Triggers when a supplier marks items on an order as backordered in fabric. | Optional - Recommended if the merchant allows suppliers to backorder items on orders. |
| **Order Canceled** | Triggers when an order is marked as canceled in fabric. | Recommended |
| **Order Closed** | Triggers when an order enters a closed status in fabric (meaning it has been shipped and invoiced). | Recommended |
| **Order Returned** | Triggers when a return is created for an order. | Optional - Recommended if the merchant manages returns in fabric. |
| **Proposal Created** | Triggers when a supplier creates a proposal (in draft status, not yet visible to the merchant). | Optional |
| **Proposal Proposed** | Triggers when a supplier submits a proposal for merchant review and approval (now visible to the merchant). | Optional - Recommended if the merchant uses "Import Requests" for merchandising. |
| **Proposal Variant Added** | Triggers when a variant is added to a proposal. | Optional |
| **RMA Approved** | Triggers when a supplier approves a return (RMA) in fabric. | Optional - Recommended if the merchant manages returns in fabric. |
| **RMA Completed** | Triggers when a return (RMA) is completed in fabric. | Optional - Recommended if the merchant manages returns in fabric. |
| **RMA Rejected** | Triggers when a supplier rejects a return (RMA) in fabric. | Optional - Recommended if the merchant manages returns in fabric. |
| **Shipment Closed** | Triggers when a shipment is marked as closed in fabric. | Recommended |
| **Shipment Created** | Triggers when a supplier creates a shipment in fabric. | Optional |
| **Shipment Updated** | Triggers when a shipments details are updated in fabric. | Optional |
| **Variant Created** | A supplier adds a new item (variant) in fabric. | Optional |
| **Variant Description Attribute Updated** | Triggers when a supplier updates the description of an item. | Optional |
| **Variant General Attribute Updated** | Triggers when a supplier updates a basic attribute of an item. | Optional |
| **Variant Identifier Attribute Updated** | Triggers when a supplier updates an item's SKU, Name, or UPC. | Optional |
| **Variant Image Attribute Updated** | Triggers when a supplier updates an item image. | Optional - Recommended if the merchant uses the supplier's SKU or UPC as their main identifier. |
| **Variant Misc Attribute Updated** | Triggers when a supplier updates a miscellaneous attribute of an item. | Optional |
| **Variant Shipping Attribute Updated** | Triggers when a supplier updates a shipping attribute of an item. | Optional |
## Configure a Webhook
1. In the main menu, click your merchant name > **Merchant Settings**.
The **Merchant Settings** page is displayed.
2. Click **Webhooks (Advanced)**.
The **Webhooks** page is displayed.
3. Click **Add Webhook**.
The **Add Webhook** window is displayed.
4. In the **Topic** field, select the webhook you would like to use.
Use the table provided in this document to learn about each webhook and what they do.
5. In the **Method** field, select a method.
fabric recommends using POST.
6. In the **URL** field, enter the `target_url`.
By default, the **Status** field is set to **Enabled**.
7. Click **Add Webhook**.
You can repeat this process to add multiple webhooks.
Once enabled, the **Webhook History** at the bottom of the **Webhooks** page provides visibility into event flow.
### Webhook History
The webhook history section shows event flows for each webhook. You can filter by a specific webhook, or view the most recent events by default. This history is retained for 24 months.
### Webhook automatic retry timing
Retries do not occur at fixed intervals. Instead, fabric uses an exponential backoff strategy combined with a small random jitter to help prevent the “thundering herd” problem—where many clients retry at the same time.
A typical retry schedule looks like this:
* 30 seconds after the first failure
* 1 minute later
* 2 minutes later
* 4 minutes later
* 8 minutes later
* 16 minutes later
* 32 minutes later
* 64 minutes later
* 2 hours later
* 2 hours later (maximum delay)
The maximum delay between retries is 2 hours. Each retry also includes a small random delay (up to 30 seconds) to spread out retry traffic and reduce server load.
If a webhook continues to fail after reaching the maximum number of retries without receiving a successful response, it will be automatically disabled.
### Enabling notifications for disabled webhooks
After 10 consecutive automatic retry failures, a webhook is automatically disabled. You can subscribe to one or more of the following webhook notifications to be alerted when delivery attempts fail or when a webhook is disabled.
Webhook Notifications:
* **Webhook Failed to Deliver**
* **Webhook Disabled After Failed Attempts**
1. In the main menu, click your merchant name > **Merchant Settings**.
The **Merchant Settings** page is displayed.
2. Click **Notifications**.
The **Notifications** page is displayed.
3. In the **Webhook Notifications** section, enter the desired user email address or distribution list you want the notifications sent to.
4. Toggle the **Disabled** button to **Enabled**.
Dropship now sends email alerts to the specified recipients when an event occurs.
## Webhook Verification Process
fabric Dropship signs all webhook requests using an **HMAC-SHA256** signature to verify authenticity and protect against tampering.
Treat your webhook secret as confidential information and store it securely. Unauthorized access to the secret would allow malicious actors to forge webhooks that appear authentic to your application.
### Generating a webhook secret
You must generate a webhook secret before verifying signatures.
1. Go to **Merchant Settings** > **Webhooks**.
2. Click **Generate Secret**.
3. Reveal the secret and copy it for use in your integration.
If the secret is ever compromised, click **Generate New Secret** and confirm to replace it.
### Using the API
1. To generate a new secret, send a POST request to:
```bash theme={null}
/v1/retailers/{id}/webhooks/webhook-secret/
```
2. (Optional) to replace an existing secret, include the following payload in your request:
```json theme={null}
{ "replace": true }
```
3. A new webhook secret will be generated and returned in the response:
```json theme={null}
{
"webhook_secret": "lpXQv26yusotoO3oVr1uHiE1hEhco8vx"
}
```
### Verifying a webhook
After you generate a webhook secret, fabric Dropship signs every webhook request using that secret. The signature is included in the fabric-dropship-signature header. To verify that a webhook is authentic, follow these steps:
1. Retrieve the raw webhook body.
Use the exact body received from the request, without modifying whitespace, formatting, or character encoding.
2. Generate the HMAC. Create an HMAC-SHA256 hash using:
Create an HMAC-SHA256 hash using your webhook secret and the raw request body.
3. Compare the signatures.
Compare your computed hash to the value in the fabric-dropship-signature header. If the values match, the webhook is authentic. If they do not match, the webhook may be unverified and should be rejected.
**Webhook Secret:**
```
lpXQv26yusotAO3oVr1yHiE1hEhco8vx
```
**Raw Body:**
```json theme={null}
{"id": 1234, "purchase_order_number": "ABC-001", "status": "closed"}
```
**Expected Signature:**
```
fabric-dropship-signature: 5d1cae4e1081325679f6e50a52ea28193e3d6871536981f0de2ed34bfc788c2d
```
By performing these checks, you can ensure that incoming webhook events are authentic and safe to process.
```Python theme={null}
import hashlib
import hmac
import os
def hmac_is_valid(body, secret, signature):
_hash = hmac.new(secret.encode('utf-8'), body.encode('utf-8'), hashlib.sha256)
hmac_calculated = _hash.hexdigest()
return hmac.compare_digest(hmac_calculated.encode('utf-8'), signature.encode('utf-8'))
signature = '5d1cae4e1081325679f6e50a52ea28193e3d68715b36981f0de2ed34fc788c2d'
raw_body = '{"id": 1234, "purchase_order_number": "ABC-001", "status": "closed"}'
webhook_secret = os.environ.get('DROPSHIP_WEBHOOK_SECRET') # read secret from env vars
is_authentic = hmac_is_valid(raw_body, webhook_secret, signature)
print(f'Webhook is authentic? {is_authentic}') # True
```