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

# Setup

> Register a webhook URL to receive automatic notifications about relevant events

# Setup

The system allows the registration of webhook URLs to receive automatic notifications about relevant events.

**Webhook URL:** HTTPS address where the events will be delivered.\
**Supported event:** onboarding\
**Notification format:** JSON payload sent via HTTP request\
**Request method:** All notifications will be sent exclusively using the POST method

## Request Body

<ParamField body="event" type="string" required>
  Type of event that will trigger the webhook. Currently, only the `onboarding` event is supported.

  Example: `onboarding`
</ParamField>

<ParamField body="url" type="string" required>
  Endpoint URL that will receive the webhook notifications for the selected event.

  URL characters: `a-z`, `A-Z` characters

  Example: `https://my-url.com/test`
</ParamField>

## Response

<ResponseField name="event" type="string">
  Type of event that will trigger the webhook. Currently, only the `onboarding` event is supported.

  Example: `onboarding`
</ResponseField>

<ResponseField name="url" type="string">
  Endpoint URL that was registered to receive webhook notifications.

  Example: `https://my-url.requestcatcher.com/test`
</ResponseField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' \
    --data '{
      "event": "onboarding",
      "url": "https://my-url.requestcatcher.com/test"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks', {
    method: 'POST',
    headers: {
      'Accept': 'application/json',
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      event: 'onboarding',
      url: 'https://my-url.requestcatcher.com/test'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

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

  url = 'https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks'
  headers = {
      'Accept': 'application/json',
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
  }
  data = {
      'event': 'onboarding',
      'url': 'https://my-url.requestcatcher.com/test'
  }

  response = requests.post(url, json=data, headers=headers)
  print(response.json())
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "event": "onboarding",
    "url": "https://my-url.requestcatcher.com/test"
      "created_at": "2024-01-15T10:30:00Z"
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "success": false,
    "error": {
      "code": "invalid_url",
      "message": "Webhook URL must use HTTPS protocol",
      "field": "url"
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "success": false,
    "error": {
      "code": "unauthorized",
      "message": "Invalid API key provided"
    }
  }
  ```
</ResponseExample>

## Webhook Payload

When an onboarding event occurs, a POST request will be sent to your webhook URL:

```json theme={null}
{
  "id": "1234-5678-90ab-cdef-1234567890ab",
  "status": "active",
  "updated_at": "2024-01-15T10:30:00Z",
  "account_id": 123,
}
```

<Info>
  The account\_id is only returned the first time in the webhook when the status is active.
</Info>

<Note>
  Your webhook endpoint must return a `200 OK` status code to acknowledge receipt. If the endpoint fails or returns an error, the system will retry delivery.
</Note>