# Webhook endpoints

> Register and manage URLs that receive VINR event notifications.

A webhook endpoint registers a URL on your server to receive event notifications from VINR. When a
notable change occurs — such as a payment succeeding or a subscription renewing — VINR sends an
HTTP POST to every matching endpoint. VINR signs each delivery using the endpoint's `secret` so you
can verify the payload before processing it.

> **Illustrative content.** Hand-authored to demonstrate the Standard/Advanced pattern; the production
> page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.

## The webhook endpoint object

- **id** `string` — Unique identifier for the webhook endpoint, e.g. `we_4Qm7vDzH`.
- **url** `string` — The destination URL that receives event payloads, e.g. `https://example.com/webhooks/vinr`.
- **status** `enum` — One of `enabled` or `disabled`. Disabled endpoints receive no deliveries.
- **enabled\_events** `array` — List of event types this endpoint subscribes to, e.g. `["payment.succeeded", "invoice.paid"]`.
  Pass `["*"]` to subscribe to all events.
- **secret** `string` — Signing secret used to verify delivery authenticity. **Shown only on create.** Use it to
  validate the `X-Vinr-Signature` header on each incoming request.
- **created** `timestamp` — Unix timestamp of when the endpoint was created.

## Create a webhook endpoint

Register a new URL and specify which event types it should receive.

`POST /v1/webhook-endpoints`

```bash
curl -X POST https://api.vinr.com/v1/webhook-endpoints \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d url=https://example.com/webhooks/vinr \
-d "enabled_events[]=payment.succeeded" \
-d "enabled_events[]=invoice.paid"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const endpoint = await vinr.webhookEndpoints.create({
url: 'https://example.com/webhooks/vinr',
enabled_events: ['payment.succeeded', 'invoice.paid'],
});
```

```python
import vinr

endpoint = vinr.WebhookEndpoint.create(
  url="https://example.com/webhooks/vinr",
  enabled_events=["payment.succeeded", "invoice.paid"],
)
```

```ruby
endpoint = Vinr::WebhookEndpoint.create(
url: 'https://example.com/webhooks/vinr',
enabled_events: ['payment.succeeded', 'invoice.paid'],
)
```

```json
{
"id": "we_4Qm7vDzH",
"url": "https://example.com/webhooks/vinr",
"status": "enabled",
"enabled_events": ["payment.succeeded", "invoice.paid"],
"secret": "whsec_k3Xp9LmR7qNv2TsB",
"created": 1716300000
}
```

## Retrieve a webhook endpoint

`GET /v1/webhook-endpoints/{id}`

```bash
curl https://api.vinr.com/v1/webhook-endpoints/we_4Qm7vDzH \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const endpoint = await vinr.webhookEndpoints.retrieve('we_4Qm7vDzH');
```

```python
import vinr

endpoint = vinr.WebhookEndpoint.retrieve("we_4Qm7vDzH")
```

```ruby
endpoint = Vinr::WebhookEndpoint.retrieve("we_4Qm7vDzH")
```

```json
{
"id": "we_4Qm7vDzH",
"url": "https://example.com/webhooks/vinr",
"status": "enabled",
"enabled_events": ["payment.succeeded", "invoice.paid"],
"created": 1716300000
}
```

## Update a webhook endpoint

Change the subscribed event types or toggle the endpoint active/disabled without deleting it.

`POST /v1/webhook-endpoints/{id}`

```bash
curl -X POST https://api.vinr.com/v1/webhook-endpoints/we_4Qm7vDzH \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d "enabled_events[]=payment.succeeded" \
-d "enabled_events[]=invoice.paid" \
-d "enabled_events[]=subscription.updated" \
-d active=true
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const endpoint = await vinr.webhookEndpoints.update('we_4Qm7vDzH', {
enabled_events: ['payment.succeeded', 'invoice.paid', 'subscription.updated'],
active: true,
});
```

```python
import vinr

endpoint = vinr.WebhookEndpoint.modify(
  "we_4Qm7vDzH",
  enabled_events=["payment.succeeded", "invoice.paid", "subscription.updated"],
  active=True,
)
```

```ruby
endpoint = Vinr::WebhookEndpoint.update(
"we_4Qm7vDzH",
enabled_events: ['payment.succeeded', 'invoice.paid', 'subscription.updated'],
active: true,
)
```

```json
{
"id": "we_4Qm7vDzH",
"url": "https://example.com/webhooks/vinr",
"status": "enabled",
"enabled_events": ["payment.succeeded", "invoice.paid", "subscription.updated"],
"created": 1716300000
}
```

## Delete a webhook endpoint

Permanently removes the endpoint. VINR will stop sending deliveries immediately.

`DELETE /v1/webhook-endpoints/{id}`

```bash
curl -X DELETE https://api.vinr.com/v1/webhook-endpoints/we_4Qm7vDzH \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

await vinr.webhookEndpoints.delete('we_4Qm7vDzH');
```

```python
import vinr

vinr.WebhookEndpoint.delete("we_4Qm7vDzH")
```

```ruby
Vinr::WebhookEndpoint.delete("we_4Qm7vDzH")
```

```json
{
"id": "we_4Qm7vDzH",
"deleted": true
}
```

## List webhook endpoints

`GET /v1/webhook-endpoints`

```bash
curl "https://api.vinr.com/v1/webhook-endpoints?limit=5" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const endpoints = await vinr.webhookEndpoints.list({ limit: 5 });
```

```python
import vinr

endpoints = vinr.WebhookEndpoint.list(limit=5)
```

```ruby
endpoints = Vinr::WebhookEndpoint.list(limit: 5)
```

```json
{
"object": "list",
"data": [
  {
    "id": "we_4Qm7vDzH",
    "url": "https://example.com/webhooks/vinr",
    "status": "enabled",
    "enabled_events": ["payment.succeeded", "invoice.paid"],
    "created": 1716300000
  }
],
"has_more": false
}
```