> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recurrente.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recurrente.com/_mcp/server.

# Registrar un webhook endpoint

POST https://app.recurrente.com/api/webhook_endpoints
Content-Type: application/json

Registra una nueva URL pública para recibir notificaciones de webhook cuando ocurran eventos en tu cuenta. No se aceptan direcciones privadas, locales ni de metadata. Con una llave TEST el endpoint se registra en el ambiente de prueba y solo recibe eventos simulados (`live_mode: false`); con una llave LIVE, en producción.


Reference: https://docs.recurrente.com/referencia-api/api-reference/webhook-endpoints/create-webhook-endpoint

## Authentication

- `X-SECRET-KEY` header (required) — Tu clave secreta de API. Una llave de cuenta (`sk_live_...`, `sk_test_...`) opera sobre su propia cuenta y, con `X-ACCOUNT-ID`, sobre sus cuentas conectadas. La llave también fija el ambiente: una `sk_test_` solo lista y resuelve objetos de prueba (`live_mode: false`) y una `sk_live_` solo objetos reales. Un ID del otro ambiente responde `404` (`401` en `/customers`). Una llave de organización (`sk_org_live_...`, `sk_org_test_...`) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con `X-ACCOUNT-ID`; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde `403` con `code: organization_key_unsupported`.

## Request

### Body (application/json)

This endpoint expects an object.

- `url` (string, required) — URL que recibirá las notificaciones de webhook
- `description` (string, optional) — (Opcional) Descripción del endpoint
- `metadata` (map from string to string, optional) — (Opcional) Metadata personalizada

## Response

### 201

Webhook endpoint creado. El `signingSecret` solo se devuelve en esta respuesta de creación; si lo pierdes, debes consultarlo en el dashboard de Svix.

- `id` (string, optional) — ID del endpoint
- `url` (string, optional) — URL que recibe los webhooks
- `description` (string, optional) — Descripción del endpoint
- `disabled` (boolean, optional) — Si el endpoint está deshabilitado
- `metadata` (map from string to string, optional) — Metadata personalizada
- `createdAt` (datetime, optional) — Fecha de creación
- `updatedAt` (datetime, optional) — Última actualización
- `signingSecret` (string, optional) — Secret para verificar las firmas de los webhooks. Solo se devuelve al crear el endpoint, no al listarlos.

## Errors

### 422 Unprocessable Entity Error

La URL no resuelve a una dirección pública

- `message` (string, optional) — Mensaje de error
- `code` (string, optional) — Código estable legible por máquinas, cuando aplica
- `refund_id` (string, optional) — ID del reembolso relacionado cuando aplica
- `endpoint` (string, optional) — Acción de API rechazada, cuando aplica
- `errors` (ErrorErrors, optional) — Detalles de errores por campo

## Types

### ErrorErrors

Detalles de errores por campo

## Examples

**Request**

```json
{
  "url": "https://example.com/webhook"
}
```

**Response**

```json
{
  "id": "ep_2fy6I9KODnHzw7Zf0ZGmMs8gEN9",
  "url": "https://example.com/webhook",
  "description": "string",
  "disabled": false,
  "metadata": {},
  "createdAt": "2024-01-15T09:30:00Z",
  "updatedAt": "2024-01-15T09:30:00Z",
  "signingSecret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}
```

**SDK Code**

```python
import requests

url = "https://app.recurrente.com/api/webhook_endpoints"

payload = { "url": "https://example.com/webhook" }
headers = {
    "X-SECRET-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://app.recurrente.com/api/webhook_endpoints';
const options = {
  method: 'POST',
  headers: {'X-SECRET-KEY': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"url":"https://example.com/webhook"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.recurrente.com/api/webhook_endpoints"

	payload := strings.NewReader("{\n  \"url\": \"https://example.com/webhook\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-SECRET-KEY", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://app.recurrente.com/api/webhook_endpoints")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-SECRET-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"https://example.com/webhook\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://app.recurrente.com/api/webhook_endpoints")
  .header("X-SECRET-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"https://example.com/webhook\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://app.recurrente.com/api/webhook_endpoints', [
  'body' => '{
  "url": "https://example.com/webhook"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-SECRET-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://app.recurrente.com/api/webhook_endpoints");
var request = new RestRequest(Method.POST);
request.AddHeader("X-SECRET-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"url\": \"https://example.com/webhook\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-SECRET-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["url": "https://example.com/webhook"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://app.recurrente.com/api/webhook_endpoints")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```