# Create a webhook endpoint

```http
POST https://smsprovider-web.vercel.app/api/v1/webhooks
```

A public HTTPS URL. The `secret` is returned only once — store it to verify signatures.

**Authentication:** `Authorization: Bearer bm_live_…` · **Required scope:** `webhooks`

## Request body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `url` | string (uri) | yes | len 0–2000 |
| `events` | `message.sent` \| `message.delivered` \| `message.failed` \| `message.expired` \| `inbound.received` \| `otp.verified` \| `otp.failed` \| `wallet.low_balance` \| `wallet.credited` \| `blacklist.added` \| `link.clicked`[] | yes | items 1–11 |

## Response

`201` — `WebhookEndpoint`

## Errors

| Status | Code |
| --- | --- |
| 400 | `validation_error` |
| 401 | `unauthorized` |
| 403 | `insufficient_scope` |
| 429 | `rate_limited` |
| 500 | `internal_error` |

## Examples

### curl
```bash
curl -X POST "https://smsprovider-web.vercel.app/api/v1/webhooks" \
  -H "Authorization: Bearer $BATLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/batler","events":["message.delivered","message.failed","inbound.received"]}'
```
### Node.js
```ts
import { BatlerSMS } from "@batler/sms";

const sms = new BatlerSMS({ apiKey: process.env.BATLER_API_KEY! });
const body = {
  "url": "https://example.com/hooks/batler",
  "events": [
    "message.delivered",
    "message.failed",
    "inbound.received"
  ]
};
const result = await sms.webhooks.create(body);
```
### PHP
```php
<?php
$ch = curl_init("https://smsprovider-web.vercel.app/api/v1/webhooks");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("BATLER_API_KEY"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode(["url" => "https://example.com/hooks/batler", "events" => ["message.delivered", "message.failed", "inbound.received"]], JSON_UNESCAPED_UNICODE),
]);
$result = json_decode(curl_exec($ch), true);
```
### Python
```python
import os, uuid, requests

resp = requests.request(
    "POST", "https://smsprovider-web.vercel.app/api/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['BATLER_API_KEY']}"},
    json={"url": "https://example.com/hooks/batler", "events": ["message.delivered", "message.failed", "inbound.received"]},
    timeout=30,
)
resp.raise_for_status()
result = resp.json()
```
### C#
```csharp
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("BATLER_API_KEY"));
var req = new HttpRequestMessage(HttpMethod.Post, "https://smsprovider-web.vercel.app/api/v1/webhooks");
req.Content = new StringContent("{\"url\":\"https://example.com/hooks/batler\",\"events\":[\"message.delivered\",\"message.failed\",\"inbound.received\"]}", System.Text.Encoding.UTF8, "application/json");
var res = await http.SendAsync(req);
var result = await res.Content.ReadAsStringAsync();
```