# 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 Infra 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.

**NOTE 1:** Registered webhooks will only work for services used in that same version.

**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.

### The Webhook Object

**Attributes**

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

### Create a Webhook

`POST /v2/webhook`

Register a new webhook URL. The subscriptions refer to which kinds of logs will be sent to the webhook URL being registered.

Available subscriptions: pix-request, pix-reversal, pix-pull-subscription, pix-pull-request, pix-internal-transaction-report, pix-key, pix-key-holmes, pix-claim, pix-infraction, pix-chargeback, pix-dispute, issuing-card, issuing-holder, issuing-purchase, issuing-invoice, credit-note or credit-holmes

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `url` | REQUIRED | The server URL that will receive the Webhook Events. |
| `subscriptions` | REQUIRED | Array of subscriptions. Possible values: "pix-request", "pix-reversal", "pix-pull-subscription", "pix-pull-request", "pix-internal-transaction-report", "pix-key", "pix-key-holmes", "pix-claim", "pix-infraction", "pix-chargeback", "pix-dispute", "issuing-card", "issuing-holder", "issuing-purchase", "issuing-invoice", "credit-note" or "credit-holmes" |

**Request**

```python
import starkinfra

webhook = starkinfra.webhook.create(
    url="https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec",
    subscriptions=[
        "pix-request",
        "pix-reversal",
        "pix-key",
        "credit-note",
        "credit-holmes"
    ]
)

print(webhook)
```

**Response**

```python
Webhook(
    id=5601079539523584,
    url=https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec,
    subscriptions=['pix-request', 'pix-reversal', 'pix-key', 'credit-note', 'credit-holmes']
)
```

### 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. |
| `limit` | OPTIONAL | Maximum number of Webhooks to be retrieved. Max = 100. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

webhooks = starkinfra.webhook.query(limit=10)

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

**Response**

```python
Webhook(
    id=5601079539523584,
    url=https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec,
    subscriptions=['pix-request', 'credit-note']
)
```

### 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 starkinfra

webhook = starkinfra.webhook.get("5601079539523584")

print(webhook)
```

**Response**

```python
Webhook(
    id=5601079539523584,
    url=https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec,
    subscriptions=['pix-request', 'credit-note']
)
```

### 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 deleted. |

**Request**

```python
import starkinfra

webhook = starkinfra.webhook.delete("5601079539523584")

print(webhook)
```

**Response**

```python
Webhook(
    id=5601079539523584,
    url=https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec,
    subscriptions=['pix-request', 'credit-note']
)
```

## Available Languages

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

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