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

# Webhooks

> Register a webhook endpoint, view your configuration, and subscribe to event types.

## The webhook object

A webhook is a callback configuration that tells Orafi where to deliver event notifications. Each business profile can have one active webhook.

<ResponseField name="id" type="string">
  Unique identifier for the webhook configuration.
</ResponseField>

<ResponseField name="url" type="string">
  Publicly accessible HTTPS endpoint that receives event payloads.
</ResponseField>

<ResponseField name="secret" type="string">
  Shared secret used to sign webhook payloads. Use this to verify that incoming requests originate from Orafi.
</ResponseField>

<ResponseField name="events" type="string[]">
  Event types the webhook is subscribed to. Only listed events are delivered.
</ResponseField>

<ResponseField name="createdAt" type="datetime">
  When the webhook was created.
</ResponseField>

<ResponseField name="updatedAt" type="datetime">
  When the webhook was last updated.
</ResponseField>

<ResponseField name="profileId" type="string">
  Business profile that owns this webhook.
</ResponseField>

### Available event types

| Event             | Description                          |
| ----------------- | ------------------------------------ |
| `payment.success` | A payment was completed successfully |
| `payment.failed`  | A payment attempt failed             |

<ResponseExample>
  ```json The webhook object theme={null}
  {
    "id": "cmjh39i5x0000v814e7owtybc",
    "url": "https://yourapp.com/webhooks/orafi",
    "secret": "whsec_a79ab7ad5d9ae565...1bcb3",
    "events": ["payment.success", "payment.failed"],
    "createdAt": "2025-12-22T11:44:41.780Z",
    "updatedAt": "2025-12-22T11:44:41.780Z",
    "profileId": "84a9f045-8a21-4ce4-a7a0-828265c0021b"
  }
  ```
</ResponseExample>

***

## Get webhook details

<div className="api-method-box">
  <span className="api-method get">GET</span> `/webhook`
</div>

Returns the current webhook configuration for the authenticated profile.

<ResponseExample>
  ```bash cURL theme={null}
  curl -X GET https://api.orafi.app/webhook \
    -H "x-api-key: ora_test_your_api_key"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.orafi.app/webhook", {
    headers: { "x-api-key": "ora_test_your_api_key" }
  });
  ```

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

  response = requests.get(
      "https://api.orafi.app/webhook",
      headers={"x-api-key": "ora_test_your_api_key"}
  )
  ```

  ```json 200 theme={null}
  {
    "success": true,
    "message": "Webhook retrieved successfully",
    "data": {
      "id": "cmjh39i5x0000v814e7owtybc",
      "url": "https://yourapp.com/webhooks/orafi",
      "secret": "whsec_a79ab7ad5d9ae5653ee11ae8b16061080da41031f3fc22811eb2865757a1bcb3",
      "events": ["payment.success", "payment.failed"],
      "createdAt": "2025-12-22T11:44:41.780Z",
      "updatedAt": "2025-12-22T11:44:41.780Z",
      "profileId": "84a9f045-8a21-4ce4-a7a0-828265c0021b"
    }
  }
  ```
</ResponseExample>

***

## Get event types

<div className="api-method-box">
  <span className="api-method get">GET</span> `/webhook/events`
</div>

Returns all event types available for webhook subscriptions.

<ResponseExample>
  ```bash cURL theme={null}
  curl -X GET https://api.orafi.app/webhook/events \
    -H "x-api-key: ora_test_your_api_key"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.orafi.app/webhook/events", {
    headers: { "x-api-key": "ora_test_your_api_key" }
  });
  ```

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

  response = requests.get(
      "https://api.orafi.app/webhook/events",
      headers={"x-api-key": "ora_test_your_api_key"}
  )
  ```

  ```json 200 theme={null}
  {
    "success": true,
    "message": "Webhook events fetched successfully",
    "data": [
      { "name": "Payment Success", "type": "payment.success" },
      { "name": "Payment Failed", "type": "payment.failed" }
    ]
  }
  ```
</ResponseExample>

***

## Register a webhook

<div className="api-method-box">
  <span className="api-method post">POST</span> `/webhook/register`
</div>

Registers or updates the webhook endpoint for your business profile. Orafi generates a `secret` automatically that you can use to verify payloads.

### Request body

<ParamField body="url" type="string" required>
  Publicly accessible HTTPS URL to receive webhook events.
</ParamField>

<ResponseExample>
  ```bash cURL theme={null}
  curl -X POST https://api.orafi.app/webhook/register \
    -H "Content-Type: application/json" \
    -H "x-api-key: ora_test_your_api_key" \
    -d '{
      "url": "https://yourapp.com/webhooks/orafi"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.orafi.app/webhook/register", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "ora_test_your_api_key"
    },
    body: JSON.stringify({
      url: "https://yourapp.com/webhooks/orafi"
    })
  });
  ```

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

  response = requests.post(
      "https://api.orafi.app/webhook/register",
      headers={
          "Content-Type": "application/json",
          "x-api-key": "ora_test_your_api_key"
      },
      json={"url": "https://yourapp.com/webhooks/orafi"}
  )
  ```

  ```json 200 theme={null}
  {
    "success": true,
    "message": "Webhook updated successfully",
    "data": {
      "id": "cmjh39i5x0000v814e7owtybc",
      "url": "https://yourapp.com/webhooks/orafi",
      "secret": "whsec_a79ab7ad5d9ae5653ee11ae8b16061080da41031f3fc22811eb2865757a1bcb3",
      "events": ["payment.success", "payment.failed"],
      "createdAt": "2025-12-22T11:44:41.780Z",
      "updatedAt": "2025-12-22T11:44:41.780Z",
      "profileId": "84a9f045-8a21-4ce4-a7a0-828265c0021b"
    }
  }
  ```
</ResponseExample>

***

## Subscribe to an event

<div className="api-method-box">
  <span className="api-method post">POST</span> `/webhook/subscribe`
</div>

Adds an event type to your existing webhook subscription.

### Request body

<ParamField body="event" type="string" required>
  The event type to subscribe to (e.g. `payment.failed`).
</ParamField>

<ResponseExample>
  ```bash cURL theme={null}
  curl -X POST https://api.orafi.app/webhook/subscribe \
    -H "Content-Type: application/json" \
    -H "x-api-key: ora_test_your_api_key" \
    -d '{
      "event": "payment.failed"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.orafi.app/webhook/subscribe", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "ora_test_your_api_key"
    },
    body: JSON.stringify({ event: "payment.failed" })
  });
  ```

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

  response = requests.post(
      "https://api.orafi.app/webhook/subscribe",
      headers={
          "Content-Type": "application/json",
          "x-api-key": "ora_test_your_api_key"
      },
      json={"event": "payment.failed"}
  )
  ```

  ```json 200 theme={null}
  {
    "success": true,
    "message": "Subscribed to event successfully",
    "data": null
  }
  ```
</ResponseExample>