> ## Documentation Index
> Fetch the complete documentation index at: https://docs.membrane.agency/llms.txt
> Use this file to discover all available pages before exploring further.

# System Webhooks

Membrane supports system-level webhooks that allow you to receive notifications about platform events. Webhooks are managed through the Admin Console and require admin permissions to configure.

### Webhook Types

Membrane supports the following webhook types:

#### User Invited to Organization (`user-invited-to-org`)

Triggered when a user is invited to join an organization workspace.

**Payload Example:**

```json theme={null}
{
  "type": "user-invited-to-org",
  "invitationUrl": "https://console.yourdomain.com/org-invitations/12345",
  "issuer": {
    "name": "John Admin",
    "email": "admin@company.com"
  },
  "user": {
    "email": "newuser@company.com"
  },
  "org": {
    "id": "org123",
    "name": "My Organization",
    "trialEndDate": "2025-05-16"
  }
}
```

#### Organization Access Requested (`org-access-requested`)

Triggered when a user requests access to an organization based on their email domain.

**Payload Example:**

```json theme={null}
{
  "type": "org-access-requested",
  "user": {
    "id": "user123",
    "email": "employee@company.com",
    "name": "Jane Employee"
  },
  "orgAdmins": [
    {
      "email": "admin@company.com",
      "orgs": [
        {
          "id": "org123",
          "name": "My Organization"
        }
      ]
    }
  ]
}
```

#### Organization Created (`org-created`)

Triggered when a new organization is created on the platform.

**Payload Example:**

```json theme={null}
{
  "type": "org-created",
  "name": "New Organization",
  "workspaceName": "Main Workspace",
  "orgId": "org456",
  "org": {
    "id": "org456",
    "name": "New Organization",
    "domains": ["company.com"],
    "trialEndDate": "2025-05-23"
  },
  "user": {
    "name": "Creator User",
    "email": "creator@company.com"
  }
}
```

### Webhook Authentication

Webhooks support HMAC-SHA256 signature verification for secure payload validation:

1. **Secret Configuration**: When creating a webhook, optionally provide a `secret` string
2. **Signature Generation**: Membrane generates an HMAC-SHA256 signature using the webhook secret
3. **Header Delivery**: The signature is sent in the `X-Signature` header with each webhook request
4. **Verification**: Verify the payload by generating the same HMAC signature on your end

**Example Verification (Node.js):**

```javascript theme={null}
const crypto = require('crypto')

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto.createHmac('sha256', secret).update(JSON.stringify(payload)).digest('hex')

  return signature === expectedSignature
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature']
  const isValid = verifyWebhook(req.body, signature, 'your-webhook-secret')

  if (!isValid) {
    return res.status(401).send('Invalid signature')
  }

  // Process webhook payload
  res.status(200).send('OK')
})
```

### Managing Webhooks

Webhooks can be managed through the Admin Console:

1. Navigate to **Admin** > **Manage Webhooks**
2. Click **Create Webhook**
3. Configure:
   * **Type**: Select the webhook event type
   * **URL**: Your webhook endpoint URL
   * **Secret**: Optional secret for HMAC verification

**API Endpoints:**

* `GET /webhooks` - List all webhooks
* `POST /webhooks` - Create a new webhook
* `GET /webhooks/:type` - Get webhook by type
* `PATCH /webhooks/:type` - Update webhook
* `DELETE /webhooks/:type` - Delete webhook

> **Note**: All webhook management operations require admin authentication via Auth0 JWT tokens.

### Webhook Configuration Requirements

* **Admin Access**: Only platform administrators can create, modify, or delete webhooks
* **Unique Types**: Only one webhook can be configured per event type
* **HTTPS Required**: Webhook URLs should use HTTPS for security
* **Response Timeout**: Webhook requests have a 30-second timeout
* **Retry Policy**: Failed webhooks are not automatically retried

### Testing Webhooks

For development and testing purposes, you can use tools like:

* **ngrok**: To expose local development servers
* **webhook.site**: To inspect webhook payloads
* **Postman**: To simulate webhook endpoints

Example ngrok setup:

```bash theme={null}
# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

# Use the generated HTTPS URL in webhook configuration
```

### Webhook handler examples

There is [a public repository](https://github.com/membranehq/admin-webhook-handler) with examples for webhook handler functions