Webhook

The Webhook object represents an endpoint configured to receive Event notifications.

A Webhook object represents an endpoint you've configured to receive Event notifications — payment successes, refunds, subscription changes, and more. Each webhook is subscribed to one or more event types and receives an HTTP POST for every matching event, signed with its secret.

A workspace may have a small, fixed number of webhooks configured at once; create returns an error once that limit is reached.

Webhook URLs must use http:// or https:// and resolve to a public address. Other schemes, and URLs that resolve to a loopback, private, or link-local address (including cloud metadata endpoints), are rejected — both at creation/update time and again at delivery time.

Endpoints

Method	Endpoint	Description
`GET`	`/v0/webhooks/list`	List all configured webhooks
`POST`	`/v0/webhooks/create`	Create a new webhook
`POST`	`/v0/webhooks/sendTestEvent`	Send a synthetic test event to subscribed webhooks
`GET`	`/v0/webhooks/{webhookId}`	Retrieve a webhook
`PATCH`	`/v0/webhooks/{webhookId}/update`	Update a webhook
`PATCH`	`/v0/webhooks/{webhookId}/archive`	Archive a webhook
`GET`	`/v0/webhooks/{webhookId}/attempts`	List a webhook's delivery attempts

The Webhook object

objectstring

Object type identifier. Always "webhook" for Webhook objects.

idstringrequired

Unique identifier (UUID) for this webhook.

urlstringrequired

The endpoint that receives event deliveries.

statusstringrequired

Current webhook status. Possible values: active, inactive

secretstringrequired

Signing secret used to verify the x-fngs-signature header on each delivery.

eventsarrayrequired

Event types this webhook is subscribed to.

createdAtinteger

Unix timestamp (milliseconds) when the webhook was created.

deletedAtinteger | null

Unix timestamp (milliseconds) when the webhook was archived. null if not archived.

The Webhook Attempt object

Each delivery attempt — success or failure — is recorded and available via the attempts endpoint.

objectstring

Object type identifier. Always "webhook_attempt" for Webhook Attempt objects.

idstringrequired

Unique identifier (UUID) for this attempt.

webhookIdstringrequired

The Webhook this attempt belongs to.

eventTypestring | null

The Event type that was delivered.

sequenceintegerrequired

Retry sequence number for this delivery. 0 is the first try.

statusCodeinteger | null

HTTP status code returned by the receiving endpoint. null if the request itself failed (timeout, connection error, blocked URL).

requestobject | null

The request body that was sent.

responseobject | null

The parsed JSON response body, if any.

createdAtinteger

Unix timestamp (milliseconds) when the attempt was made.

Example response

{
  "status": "success",
  "data": {
    "webhook": {
      "object": "webhook",
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "url": "https://example.com/webhooks/fungies",
      "status": "active",
      "secret": "your-webhook-signing-secret",
      "events": ["payment_success", "subscription_cancelled"],
      "createdAt": 1717200000000,
      "deletedAt": null
    }
  }
}

Events

The notification payloads webhooks deliver

Webhook Setup Guide

Configuring and verifying webhook deliveries