> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recursiv.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recursiv.io/_mcp/server.

# 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

| Method            | Description                     |
| ----------------- | ------------------------------- |
| `register(input)` | Register a new inbound webhook. |
| `list()`          | List all registered webhooks.   |
| `delete(id)`      | Delete a webhook registration.  |

## Register a webhook

```typescript
const { data: webhook } = await r.webhooks.register({
  provider: 'stripe',
  project_id: 'proj_123',
  events: ['payment_succeeded', 'subscription_updated'],
  handler_code: `async (payload) => {
    // This runs in your project sandbox when Stripe sends an event
    console.log('Payment received:', payload.data.object.amount);
  }`,
});

console.log(webhook.id);       // Webhook ID
console.log(webhook.endpoint); // /api/v1/webhooks/inbound/{id}
```

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

## List webhooks

```typescript
const { data: webhooks } = await r.webhooks.list();

for (const wh of webhooks) {
  console.log(`${wh.provider} — ${wh.status} — last received: ${wh.last_received_at}`);
}
```

## Delete a webhook

```typescript
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

> **Note**
>
> Webhook handler code runs in your project's E2B sandbox with a 30-second timeout. The handler has access to your project's database and environment.