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

# Create Webhook Endpoint

> Create a new webhook endpoint to receive event notifications

# Create Webhook Endpoint

Creates a new webhook endpoint to receive event notifications.

## Request

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key
</ParamField>

<ParamField body="url" type="string" required>
  The HTTPS URL where webhook events will be sent
</ParamField>

<ParamField body="events" type="array" required>
  Array of event types to subscribe to
</ParamField>

<ParamField body="description" type="string">
  Optional description for this endpoint
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="endpoint" type="object">
      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Unique webhook endpoint identifier
        </ResponseField>

        <ResponseField name="url" type="string">
          Webhook URL
        </ResponseField>

        <ResponseField name="events" type="array">
          Subscribed event types
        </ResponseField>

        <ResponseField name="isActive" type="boolean">
          Whether the endpoint is active
        </ResponseField>

        <ResponseField name="description" type="string">
          Endpoint description
        </ResponseField>

        <ResponseField name="createdAt" type="string">
          ISO 8601 creation timestamp
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="secret" type="string">
      Signing secret for verifying payloads. **Only shown once on creation!**
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.swiftpay.cx/api/webhooks \
    -H "Authorization: Bearer mp_live_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://yoursite.com/webhooks/swiftpay",
      "events": [
        "checkout.succeeded",
        "checkout.failed",
        "withdrawal.paid"
      ],
      "description": "Production webhook handler"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.swiftpay.cx/api/webhooks", {
     method: "POST",
     headers: {
        Authorization: "Bearer mp_live_your_api_key",
        "Content-Type": "application/json",
     },
     body: JSON.stringify({
        url: "https://yoursite.com/webhooks/swiftpay",
        events: ["checkout.succeeded", "checkout.failed", "withdrawal.paid"],
        description: "Production webhook handler",
     }),
  });

  const webhook = await response.json();

  // IMPORTANT: Save the secret securely - it's only shown once!
  console.log("Webhook secret:", webhook.data.secret);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.swiftpay.cx/api/webhooks',
      headers={
          'Authorization': 'Bearer mp_live_your_api_key',
          'Content-Type': 'application/json'
      },
      json={
          'url': 'https://yoursite.com/webhooks/swiftpay',
          'events': [
              'checkout.succeeded',
              'checkout.failed',
              'withdrawal.paid'
          ],
          'description': 'Production webhook handler'
      }
  )

  webhook = response.json()

  # IMPORTANT: Save the secret securely - it's only shown once!
  print(f"Webhook secret: {webhook['data']['secret']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "data": {
      "endpoint": {
        "id": "wh_abc123",
        "url": "https://yoursite.com/webhooks/swiftpay",
        "events": [
          "checkout.succeeded",
          "checkout.failed",
          "withdrawal.paid"
        ],
        "isActive": true,
        "description": "Production webhook handler",
        "createdAt": "2024-01-15T10:30:00Z"
      },
      "secret": "whsec_1234567890abcdef"
    }
  }
  ```

  ```json 400 theme={null}
  {
     "success": false,
     "error": {
        "type": "validation_error",
        "message": "URL must be HTTPS",
        "requestId": "req_abc123"
     }
  }
  ```
</ResponseExample>

## Available Events

### Checkout Events

| Event                | Description            |
| -------------------- | ---------------------- |
| `checkout.succeeded` | Payment was successful |
| `checkout.failed`    | Payment failed         |

### Withdrawal Events

| Event               | Description                   |
| ------------------- | ----------------------------- |
| `withdrawal.paid`   | Withdrawal processed and paid |
| `withdrawal.failed` | Withdrawal failed to process  |

<Warning>
  **Save the secret immediately!** The webhook signing secret is only returned
  when creating the endpoint. Store it securely - you'll need it to verify
  webhook signatures.
</Warning>