Webhooks

Webhooks form the backbone of modern API development, allowing you to monitor changes in our systems and trigger actions in external applications, such as sending text messages or updating payment statuses. Zuper provides built-in webhook support, enabling users to register an HTTP/HTTPS URL that activates when an event occurs within Zuper.

With options to create, update, and delete webhooks, the system eliminates the need for periodic API calls and ensures that new updates are seamlessly integrated into the webhook.

Navigation: Settings -> Developer Hub -> Webhooks

1. From the settings, select “Developer Hub,” choose “Webhooks,” and click “+New Webhook.”

2. Create a new webhook by filling in the following details:

• Webhook Name (Mandatory) - Enter the unique name for the webhook. 
• Module (Mandatory) - Choose the applicable module. 
• Webhook Event (Mandatory) - Choose the applicable webhook’s event. 
• Request Method and Request URL -  Choose the applicable method: POST, GET, PUT, and DELETE. A webhook request URL is the unique URL provided by a service or application that allows another application to send data directly to it.
• Headers - Add the key and the respective values. 

HTTP Method	General Purpose (in REST APIs)	Webhook Context	Common Use Case in Webhooks	Best Practices
GET	Retrieve data without modifying it (idempotent, safe).	Rarely used for delivery (no body for payloads); supported in some tools for simple queries or polling-like triggers.	Fetching webhook configuration or metadata.	Avoid sensitive data; use query params sparingly. Limit to read-only ops.
POST	Create new resources or submit data (non-idempotent).	The default and most common for webhook payloads. Sends JSON/XML bodies with event details.	Delivering event data.	Always include a signature/header for verification. Expect retries on failure.
PUT	Update/replace an entire resource (idempotent).	Used in scenarios needing complete resource replacement; less common but supported for updates.	Updating webhook subscriptions.	Ensure idempotency—repeated calls shouldn’t create duplicates. Use for complete overwrites, not partial updates.
DELETE	Remove a resource (idempotent).	Primarily for management, not delivery.	Unsubscribing or deleting a webhook endpoint.	Confirm deletion with a 204 No Content response. Use auth tokens to prevent unauthorized removals.

Click “Create” to add the new webhook. 

3. The new webhook secret key is generated successfully.

4. Click icon to Edit Webhook, Copy Webhook URL, and Activate/Deactivate Webhook.

5. Click “Webhook History” to view the list of webhook executions.

​

Automatic webhook deactivation

A webhook works only when the system receiving it is ready to accept data. That receiving system listens at an endpoint, which is the request URL you entered when you created the webhook. If the endpoint goes offline, moves to a new address, or starts rejecting requests, every event Zuper sends to it fails. Over time, these failures fill your Webhook History and can hide the fact that your integration has stopped working.

To protect your integrations, Zuper automatically deactivates a webhook that fails consistently. Think of it like a circuit breaker in your home. When something keeps going wrong, the breaker trips, so you can fix the cause before you switch the power back on. After you resolve the issue at your endpoint, you can reactivate the webhook in a few steps.

​

When Zuper deactivates a webhook

Zuper checks the delivery results of your webhooks once a day. During each check, Zuper deactivates any webhook that meets either of the following conditions.

Condition	What triggers deactivation
High-volume failures	Zuper made 100 or more delivery attempts in the 24 hours before the daily check, and every attempt failed.
Consecutive daily failures	Every delivery attempt failed on each of the last 10 full calendar days, ending the day before the check. At least one attempt also occurred on each of those days.

Zuper counts each event as one delivery attempt, however many times it retries that event. If a retry later succeeds, the event counts as delivered. Because both conditions require every attempt to fail, a single successful delivery during the period keeps the webhook active.

​

What happens after deactivation

When Zuper deactivates a webhook, its status changes to Inactive on the Webhooks page. At the same time, Zuper sends an email to the user who created the webhook, so the person who set up the integration knows to investigate. Zuper then stops sending events to that endpoint until you reactivate the webhook.

​

Reactivate a webhook

Before you reactivate a webhook, review its failed deliveries in Webhook History and fix the cause at your endpoint. Once your endpoint is ready, follow these steps.

1. Go to Settings, then select Developer Hub.
2. Select Webhooks.
3. Find the webhook that shows the Inactive status.
4. Select the icon next to the webhook.
5. Select Activate Webhook.
   The status changes to Active, and Zuper resumes sending events to your endpoint.

After you reactivate a webhook, trigger a test event and check Webhook History. A successful delivery confirms that your fix worked.

​

Webhooks linked to Workflow Builder

When you create a webhook through Workflow Builder, it stays linked to the workflow that created it. Because of this link, the webhook status follows the workflow status, as the following table shows.

When you	The linked webhook
Activate the workflow	Becomes active.
Deactivate the workflow	Becomes inactive automatically.
Reactivate the workflow	Becomes active again automatically.

To keep the workflow and its webhook in sync, activate or deactivate workflow-linked webhooks from Workflow Builder, not from the Webhooks page.

Best Practices

• Ensure your Request URL is publicly accessible and can handle the specified HTTP method.
• Use headers to include authentication tokens or other metadata as needed.
• Test your webhook configuration to confirm it receives events correctly.

Leveraging Zuper API Keys effectively strengthens the security and efficiency of your integrations. Protect your keys by storing them securely, rotating them regularly, and monitoring their usage to maintain a reliable and safe interaction with the Zuper API.