Skip to main content

​
Webhooks API

The webhooks module gives you programmatic control over Webhook Apps, Endpoints, and Event Deliveries. While normally configured via your application dashboard, this module is incredibly powerful for applications that provision webhooks dynamically on behalf of their users. 
import { WachtClient } from "@wacht/backend";

const client = new WachtClient({ apiKey: process.env.WACHT_API_KEY });

​
Webhook Apps

Apps represent a logical grouping of events.

​
createWebhookApp(request)

Define a new broadcast channel. 
const app = await client.webhooks.createWebhookApp({
  name: "Payments Integration",
  slug: "payments-int",
  description: "Fires when invoices are paid."
});
​
request
CreateWebhookAppRequest
required
  • client.webhooks.listWebhookApps(options)
  • client.webhooks.getWebhookApp(appSlug)
  • client.webhooks.updateWebhookApp(appSlug, request)
  • client.webhooks.deleteWebhookApp(appSlug)
  • client.webhooks.rotateWebhookSecret(appSlug)

​
Endpoint Management

Endpoints define where Wacht sends the events triggered by an App.

​
createWebhookEndpoint(appSlug, request)

Bind a listener to an App. 
await client.webhooks.createWebhookEndpoint("payments-int", {
  url: "https://my-backend.com/webhooks/receive",
  description: "Primary Production Listener",
  events: ["invoice.paid", "invoice.past_due"]
});
​
appSlug
string
required
The unique slug indentifier of the target Webhook App.
​
request
CreateWebhookEndpointRequest
required
  • client.webhooks.listWebhookEndpoints(appSlug, options)
  • client.webhooks.updateWebhookEndpoint(appSlug, endpointId, request)
  • client.webhooks.deleteWebhookEndpoint(appSlug, endpointId)
  • client.webhooks.testWebhookEndpoint(appSlug, endpointId, request)
  • client.webhooks.reactivateWebhookEndpoint(endpointId)

​
Event Deliveries

Wacht meticulously tracks the success and failure states of every webhook delivery. You can query this data programmatically.

​
listWebhookDeliveries(appSlug, options)

Retrieve a historical log of events sent to an app. 
const deliveries = await client.webhooks.listWebhookDeliveries("payments-int", {
  status: "failed", // Only find failed deliveries
  limit: 25
});
​
appSlug
string
required
The app identifier.
​
options
ListWebhookDeliveriesOptions

​
replayWebhookDelivery(appSlug, deliveryId)

Manually force a failed payload to be re-transmitted to its endpoint. 
await client.webhooks.replayWebhookDelivery("payments-int", "del_abc123");
​
appSlug
string
required
The target app identifier.
​
deliveryId
string
required
The specific delivery ID tracking token to manually resend.
  • client.webhooks.getWebhookDelivery(appSlug, deliveryId)
  • client.webhooks.replayWebhookDeliveries(appSlug, request)

​
Triggering Custom Events

You can use Wacht as a generic event bus to emit custom events to registered endpoints. 
await client.webhooks.triggerWebhook("payments-int", {
  event_name: "custom.billing.processed",
  payload: {
     amount: 5000,
     currency: "USD",
     customer: "Alice"
  }
});
​
appSlug
string
required
The app broadcasting the new custom event.
​
request
TriggerWebhookRequest
required

​
Analytics

Fetch delivery performance statistics.
  • client.webhooks.getWebhookStats(appSlug)
  • client.webhooks.getWebhookAnalytics(appSlug, options)
  • client.webhooks.getWebhookTimeseries(appSlug, options)