Webhooks

Overview

Register inbound webhook endpoints to receive events from external services (Stripe, GitHub, custom). When an event arrives, Recursiv can execute handler code in your project’s sandbox automatically.

All webhook methods are available on r.webhooks.

Methods

Register a webhook

1
const { data: webhook } = await r.webhooks.register({
2
  provider: 'stripe',
3
  project_id: 'proj_123',
4
  events: ['payment_succeeded', 'subscription_updated'],
5
  handler_code: `async (payload) => {
6
    // This runs in your project sandbox when Stripe sends an event
7
    console.log('Payment received:', payload.data.object.amount);
8
  }`,
9
});
10
11
console.log(webhook.id);       // Webhook ID
12
console.log(webhook.endpoint); // /api/v1/webhooks/inbound/{id}

Point your Stripe webhook URL to: https://api.recursiv.io${webhook.endpoint}

List webhooks

1
const { data: webhooks } = await r.webhooks.list();
2
3
for (const wh of webhooks) {
4
  console.log(`${wh.provider} — ${wh.status} — last received: ${wh.last_received_at}`);
5
}

Delete a webhook

1
await r.webhooks.delete('webhook_id');

How it works

1. You register a webhook with a provider name and optional handler code
2. Recursiv gives you an endpoint URL to configure in the external service
3. When the external service sends an event, Recursiv receives it
4. If handler code is defined, it executes in your project’s sandbox with the event payload
5. The event is also published to the platform event stream for other consumers