Webhook Endpoints

Register webhook endpoints to receive real-time notifications for payment events. Manage endpoints, rotate secrets, and verify signatures programmatically.

Create a webhook endpoint

Create endpointtypescript

const endpoint = await noderails.webhookEndpoints.create({
  url: 'https://yoursite.com/webhooks/noderails',
  events: [
    'payment.captured',
    'payment.settled',
    'subscription.created',
  ],
});

// Save the signing secret (only returned on creation)
console.log(endpoint.id);     // Endpoint ID
console.log(endpoint.secret); // "whsec_..." — store this securely

⚠️

Save the secret

The signing secret is only returned when you create the endpoint or rotate the secret. Store it securely in your environment variables.

List endpoints

Listtypescript

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

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

Send a test ping

Test endpoint deliverytypescript

await noderails.webhookEndpoints.testPing('endpoint-id');

List webhook deliveries

List deliveriestypescript

const result = await noderails.webhookEndpoints.listDeliveries('endpoint-id', {
  limit: 20,
  status: 'FAILED',
});

console.log(result.items);
console.log(result.nextCursor);

Update events

Updatetypescript

await noderails.webhookEndpoints.update('endpoint-id', {
  events: ['payment.captured', 'payment.settled'],
});

Rotate the signing secret

Rotate the secret if you suspect it has been compromised. This invalidates the old secret immediately.

Rotate secrettypescript

const rotated = await noderails.webhookEndpoints.rotateSecret('endpoint-id');
console.log(rotated.secret); // New "whsec_..." value

Delete an endpoint

Deletetypescript

await noderails.webhookEndpoints.delete('endpoint-id');

Verifying webhook signatures

When you receive a webhook, verify its signature before processing. The constructEvent method is a static utility that works without initializing the SDK client.

Express handler with verificationtypescript

import { NodeRails } from '@noderails/sdk';

app.post('/webhooks/noderails', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = NodeRails.webhooks.constructEvent(
      req.body,                                        // Raw body (Buffer or string)
      req.headers['x-noderails-signature'] as string,  // Signature header
      req.headers['x-noderails-timestamp'] as string,  // Timestamp header
      process.env.WEBHOOK_SECRET!,                     // Your signing secret
    );

    // event is now verified and parsed
    console.log(event.event); // e.g., "payment.captured"
    console.log(event.data);  // The payment intent / subscription object

    res.sendStatus(200);
  } catch (err) {
    // Signature invalid or timestamp too old
    console.error('Webhook verification failed:', err);
    res.sendStatus(400);
  }
});

⚠️

Always verify signatures

Never process a webhook without verifying its signature first. The constructEvent method throws a SignatureVerificationError if the signature is invalid or the timestamp is too old (5 minute tolerance).

Methods reference

Method	Description
`create(params)`	Create a new webhook endpoint
`list()`	List all endpoints
`update(id, params)`	Update endpoint configuration
`delete(id)`	Delete an endpoint
`rotateSecret(id)`	Rotate the signing secret
`testPing(id)`	Send a test webhook delivery
`listDeliveries(id, params?)`	List webhook deliveries with cursor pagination

Static Method	Description
`NodeRails.webhooks.constructEvent(...)`	Verify signature and parse webhook payload

Response body reference

All responses are wrapped in { success: true, data: ... }. The fields below describe what's inside data.

`create()` response

WebhookEndpoint (create)

idstringUnique endpoint ID (UUID)

urlstringYour webhook URL

eventsstring[]Array of event types subscribed to

activebooleanWhether the endpoint is active

createdAtstringISO 8601 creation timestamp

secretstringSigning secret (only returned on create and rotateSecret)

⚠️

Secret is only returned once

The secret field is only included when you create the endpoint or rotate its secret. It is never returned in list() or update() responses.

`list()` response

WebhookEndpoint (list)

idstringEndpoint ID

urlstringWebhook URL

eventsstring[]Subscribed event types

activebooleanWhether active

createdAtstringISO 8601 creation timestamp

updatedAtstringISO 8601 last update timestamp

`update()` response

WebhookEndpoint (update)

idstringEndpoint ID

urlstringWebhook URL

eventsstring[]Updated event types

activebooleanWhether active

updatedAtstringISO 8601 last update timestamp

`rotateSecret()` response

Rotate secret

secretstringNew 64-character hex signing secret

`delete()` response

Returns 204 No Content (no response body).