# Webhook

You can create webhook subscriptions to receive events whenever a new log is created. We send the event by making a POST request to your endpoint URL. The event will be delivered with a digital signature (headers["Digital-Signature"]), which can be verified using the Stark Bank public key. This key is recoverable by a GET request to /v2/public-key.

If your endpoint URL does not return a 200 status, the webhook service will try again at most three times. The interval between each attempt is 5 min, 30 min and finally 120 min. In case the event cannot be delivered after those three attempts, we will stop trying to deliver the message.

The event sent to the endpoint URL has the structure shown in the example, where the content of the log sent will depend on the event subscription.

New webhooks use "parallel" delivery by default, so events are not guaranteed to arrive in order. For example, the first event received for an Invoice may contain a log other than "created". Your webhook handler must tolerate out-of-order events instead of relying on their delivery sequence.

**NOTE 1:** Registered webhooks will only work for services used in that same version. For example, if you create a transfer in v2, its logs will only trigger v2 webhooks and v1 webhooks would ignore its events.

**NOTE 2:** Even if you use Webhook, we strongly recommend that you create a daily task to get all undelivered events and set them as delivered. It's important to add redundancy and resilience to your system, preventing you from having outdated information just in case your system is temporarily unable to receive our Webhook events.

### The Webhook object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the webhook subscription. |
| `subscriptions` | LIST OF STRINGS | List of subscribed event types. |
| `url` | STRING | Endpoint URL that receives webhook events. |

### Create a Webhook

`POST /v2/webhook`

Here you can register a new webhook URL. The subscriptions refer to which kinds of logs will be sent to the webhook URL being registered. The subscriptions must be in transfer, boleto, boleto-payment, utility-payment, brcode-payment, boleto-holmes, deposit, darf-payment, tax-payment, payment-request, verified-account, corporate-purchase, corporate-card, merchant-purchase, merchant-installment, merchant-card, invoice-pull-subscription, invoice-pull-request or invoice.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `subscriptions` | REQUIRED | Array of subscriptions. Possible values: "deposit", "invoice", "invoice-pull-subscription", "invoice-pull-request", "brcode-payment", "transfer", "utility-payment", "boleto", "boleto-payment", "darf-payment", "tax-payment", "payment-request", "verified-account", "corporate-purchase", "corporate-card", "merchant-purchase", "merchant-installment", "merchant-card" or "boleto-holmes" |
| `url` | REQUIRED | The server URL that will receive the Webhook Events. |

**Request**

```python
import starkbank

webhook = starkbank.webhook.create(
    url="https://winterfell.westeros.gov/events-from-stark-bank",
    subscriptions=[
        "boleto",
        "boleto-payment",
        "transfer",
        "utility-payment"
    ]
)

print(webhook)
```

**Response**

```python
Webhook(
    id=6225875037061120,
    subscriptions=['boleto', 'boleto-payment', 'transfer', 'utility-payment'],
    url=https://winterfell.westeros.gov/events-from-stark-bank
)
```

### List Webhooks

`GET /v2/webhook`

Get a list of non-deleted webhooks in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Maximum number of Webhooks to be retrieved. Max = 100. |

**Request**

```python
import starkbank

webhooks = starkbank.webhook.query()

for webhook in webhooks:
    print(webhook)
```

**Response**

```python
Webhook(
    id=6225875037061120,
    subscriptions=['boleto', 'boleto-payment', 'transfer', 'utility-payment'],
    url=https://winterfell.westeros.gov/events-from-stark-bank
)
```

### Get a Webhook

`GET /v2/webhook/:id`

Get a single Webhook by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the webhook entity |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

webhook = starkbank.webhook.get("6225875037061120")

print(webhook)
```

**Response**

```python
Webhook(
    id=6225875037061120,
    subscriptions=['boleto', 'boleto-payment', 'transfer', 'utility-payment'],
    url=https://winterfell.westeros.gov/events-from-stark-bank
)
```

### Delete a Webhook

`DELETE /v2/webhook/:id`

Delete a single Webhook subscription.

**NOTE:** This action cannot be undone.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Webhook to be canceled. |

**Request**

```python
import starkbank

webhook = starkbank.webhook.delete("6225875037061120")

print(webhook)
```

**Response**

```python
Webhook(
    id=6225875037061120,
    subscriptions=['boleto', 'boleto-payment', 'transfer', 'utility-payment'],
    url=https://winterfell.westeros.gov/events-from-stark-bank
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkbank.com/api/v2/webhook-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/webhook-node.md)
- [PHP](https://docs.starkbank.com/api/v2/webhook-php.md)
- [Java](https://docs.starkbank.com/api/v2/webhook-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/webhook-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/webhook-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/webhook-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/webhook-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/webhook-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/webhook-curl.md)