Webhook Endpoints

Manage your webhook endpoint registrations. Create endpoints, configure which events they receive, rotate signing secrets, and inspect delivery history.

💡

Base path

Webhook endpoints are scoped to an app: /apps/:appId/webhooks. The SDK handles this automatically using the appId from your client configuration.

Create a webhook endpoint

POST/apps/:appId/webhooks

Request body

Parameter	Type	Required	Description
`url`	`string`	Yes	HTTPS URL to receive events
`events`	`string[]`	Yes	Events to subscribe to (min 1)

SDK exampletypescript

const endpoint = await noderails.webhookEndpoints.create({
  url: 'https://example.com/webhooks/noderails',
  events: [
    'payment_intent.captured',
    'payment_intent.refunded',
    'invoice.paid',
    'subscription.cancelled',
  ],
});

console.log(endpoint.id);     // "we_abc123"
console.log(endpoint.secret); // "whsec_..." — save this!

⚠️

Save the secret

The webhook signing secret is only returned once, when the endpoint is first created. Store it securely. You'll need it to verify webhook signatures.

List webhook endpoints

GET/apps/:appId/webhooks

SDK exampletypescript

const endpoints = await noderails.webhookEndpoints.list();

for (const ep of endpoints) {
  console.log(ep.url, ep.events, ep.active);
}

Update a webhook endpoint

PUT/apps/:appId/webhooks/:webhookId

Parameter	Type	Required	Description
`url`	`string`	No	Updated endpoint URL
`events`	`string[]`	No	Updated event list
`active`	`boolean`	No	Enable/disable endpoint

SDK exampletypescript

const updated = await noderails.webhookEndpoints.update('we_abc123', {
  events: ['payment_intent.captured', 'payment_intent.settled'],
  active: true,
});

Delete a webhook endpoint

DELETE/apps/:appId/webhooks/:webhookId

Permanently deletes a webhook endpoint. Returns 204 No Content.

SDK exampletypescript

await noderails.webhookEndpoints.del('we_abc123');

Rotate signing secret

POST/apps/:appId/webhooks/:webhookId/rotate-secret

Generates a new signing secret for the endpoint. The old secret is immediately invalidated.

SDK exampletypescript

const rotated = await noderails.webhookEndpoints.rotateSecret('we_abc123');
console.log(rotated.secret); // "whsec_..." — new secret

Send a test ping

POST/apps/:appId/webhooks/:webhookId/test-ping

Sends a test event to the endpoint to verify connectivity.

SDK exampletypescript

await noderails.webhookEndpoints.testPing('we_abc123');

List deliveries

GET/apps/:appId/webhooks/:webhookId/deliveries

Retrieves the delivery history for a webhook endpoint (cursor-based pagination).

Query parameters

Parameter	Type	Description
`status`	`string`	Filter by delivery status
`cursor`	`string`	Cursor for pagination
`limit`	`number`	Number of results to return

SDK exampletypescript

const deliveries = await noderails.webhookEndpoints.listDeliveries(
  'we_abc123',
  { limit: 20 },
);

for (const d of deliveries.data) {
  console.log(d.eventType, d.status, d.responseCode);
}

Response object

All responses are wrapped in { "success": true, "data": ... }. Delete returns 204 No Content.

WebhookEndpoint object (create)json

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "url": "https://example.com/webhooks/noderails",
    "events": [
      "payment_intent.captured",
      "payment_intent.refunded",
      "invoice.paid"
    ],
    "active": true,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "secret": "whsec_a1b2c3d4e5f6..."
  }
}

WebhookEndpoint fields

idstringUnique webhook endpoint UUID

urlstringHTTPS URL that receives events

eventsstring[]Subscribed event types

activebooleanWhether the endpoint is enabled

createdAtstringISO 8601 creation timestamp (create and list only)

updatedAtstringISO 8601 last-update timestamp (list and update only)

secretstringWebhook signing secret (only returned on create)

⚠️

Field availability varies by endpoint

Create returns id, url, events, active, createdAt, and secret. List returns the same except secret and adds updatedAt. Update returns id, url, events, active, updatedAt (no createdAt or secret). Rotate secret returns only { "secret": "whsec_..." }.

Test ping response

Test ping resultjson

{
  "success": true,
  "data": {
    "success": true,
    "statusCode": 200,
    "responseBody": "OK",
    "error": null
  }
}

Delivery history

Deliveries use cursor-based pagination:

Deliveries responsejson

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "del-uuid",
        "event": "payment_intent.captured",
        "status": "DELIVERED",
        "responseStatus": 200,
        "attempts": 1,
        "createdAt": "2025-01-15T10:30:00.000Z",
        "deliveredAt": "2025-01-15T10:30:01.000Z",
        "nextRetryAt": null
      }
    ],
    "nextCursor": null
  }
}