# Webhooks

## About Our Webhooks 📣

Receive notifications/alerts on every new transaction or transaction status change in any of your inabit organizations within your account, as well as fee updates for a transaction.

There are two endpoints you can use with our Webhooks:

* [Create Subscription](#create-subscription) - registering to the subscription service
* [Delete Subscription](#delete-subscription) - deleting an existing subscription

{% hint style="info" %}
Webhook endpoints are accessible only to the following user roles:\
**Owner**, **Admin**, **API Admin**
{% endhint %}

{% hint style="warning" %}
Our webhook service is currently limited to 1 subscription per organization.
{% endhint %}

* Events Handled:
  * **New Transaction Event**
  * **Transaction Status Updates** (Incl. txn fee updates)
* Supported transaction types:
  * **Received** (Deposits)
  * **Sent** (Withdrawals)

For further information regarding transaction types (events), refer to the [Notification Types ](/api-reference/remote-approver-app/webhooks/notification-types.md)subpage.

## Create Subscription

In order to create a subscription on our GraphQL API, you'll need to call the following **mutation**:

```graphql
mutation CreateSubscription($data: SubscriptionCreateInput!) {
  createSubscription(data: $data) {
  id,
  token
  }
}
```

### Headers

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

### **Body (**<mark style="color:orange;">SubscriptionCreateInput</mark> object)

| Name                                  | Type   | Description                                               |
| ------------------------------------- | ------ | --------------------------------------------------------- |
| id<mark style="color:red;">\*</mark>  | string | ID of the organization in inabit                          |
| url<mark style="color:red;">\*</mark> | string | URL for the webhook service to send notifications towards |

Example body:

```graphql
{
  "data": {
    "organization": {
      "id": "clu1dzpny0007vjto1gxhl5my"   # inabit organization Id
    },
    "url": "https://studio.apollographql.com",   # Webhook for subscriber
  }
}
```

### Response

{% tabs %}
{% tab title="🟢 Success" %}

```graphql
{
  "data": {
    "createSubscription": {
      "id": "clugv892y0000vjhga8ugol38",   # Created subscription Id
      "token": "sub_c028ef8d-b8b9-49c0-b5a9-f7451884b834"   # Unique generated token recognized by inabit
    }
  }
}
```

{% endtab %}

{% tab title="🔴 Error: Subscriptions Limit" %}

```graphql
{
  "errors": [
    {
      "message": "INTERNAL_SERVER_ERROR",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "createSubscription"
      ],
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "There's already an active subscription for this organization. (organization: clu1dzpny0007vjto1gxhl5my)",
        "exception": {
          "message": "INTERNAL_SERVER_ERROR",
          "stacktrace": [
            "Error: There's already an active subscription for this organization. (organization: clu1dzpny0007vjto1gxhl5my)",
            "    at SubscriptionResolver.createSubscription (C:\\Users\\Ori Botan\\Documents\\inabit\\inabit\\server\\src\\subscription\\subscription.resolver.ts:81:13)"
          ]
        }
      }
    }
  ],
  "data": null
}
```

{% endtab %}

{% tab title="🔴 Error: Internal Server Error" %}

```graphql
{
  "errors": [
    {
      "message": "INTERNAL_SERVER_ERROR",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "createSubscription"
      ],
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "Create subscription failed (organization: clu1dzpny0007vjto1gxhl5my)",
        "exception": {
          "message": "INTERNAL_SERVER_ERROR",
          "stacktrace": [
            "Error: Create subscription failed (organization: clu1dzpny0007vjto1gxhl5my)",
            "    at SubscriptionResolver.createSubscription (C:\\Users\\Ori Botan\\Documents\\inabit\\inabit\\server\\src\\subscription\\subscription.resolver.ts:81:13)"
          ]
        }
      }
    }
  ],
  "data": null
}
```

{% endtab %}
{% endtabs %}

In the mutation's response, the following is retrieved:

**ID** - The ID of the subscription that was created.

**Token** - A unique token generated by inabit.

* The token will be the identifying the webhook resource for the subscriber set as a header: 'authorization' : (i.e. - `sub_c028ef8d-b8b9-49c0-b5a9-f7451884b834`)

{% hint style="success" %}
Remember - You can always query data and fetch all of an organization's subscriptions in case its hard to keep track, see query below.
{% endhint %}

```graphql
query Subscriptions($where: SubscriptionWhereInput) {
  subscriptions(where: $where) {
  id  
  token
  }
}
```

#### **Body (**<mark style="color:orange;">SubscriptionWhereInput</mark> object)

| Name                                 | Type   | Description                      |
| ------------------------------------ | ------ | -------------------------------- |
| id<mark style="color:red;">\*</mark> | string | ID of the organization in inabit |

## Delete Subscription

In order to delete a subscription, the following **mutation** needs to be used:

```graphql
mutation DeleteSubscription($where: SubscriptionWhereUniqueInput!) {
  deleteSubscription(where: $where) {
  id  
  }
}
```

### Headers

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

### **Body (**<mark style="color:orange;">SubscriptionWhereUniqueInput</mark> object)

| Name                                 | Type   | Description     |
| ------------------------------------ | ------ | --------------- |
| id<mark style="color:red;">\*</mark> | string | Subscription ID |

Example body:

```graphql
body:
{
  "where": {
    "id": "clu5bxctk0003vje4n4pqfdya"   # Subscription Id
  }
}
```

### Response

{% tabs %}
{% tab title="🟢 Success" %}

```graphql
{
  "data": {
    "deleteSubscription": {
      "id": "clugwvbm70007vj4w74gxch3u"
    }
  }
}
```

{% endtab %}

{% tab title="🔴 Error: Internal Server Error" %}

```graphql
{
  "errors": [
    {
      "message": "INTERNAL_SERVER_ERROR",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "deletesubscription"
      ],
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "Delete subscription failed (organization: clu1dzpny0007vjto1gxhl5my)",
        "exception": {
          "message": "INTERNAL_SERVER_ERROR",
          "stacktrace": [
            "Error: Delete subscription failed (organization: clu1dzpny0007vjto1gxhl5my)",
            "    at SubscriptionResolver.deleteSubscription (C:\\Users\\Ori Botan\\Documents\\inabit\\inabit\\server\\src\\subscription\\subscription.resolver.ts:81:13)"
          ]
        }
      }
    }
  ],
  "data": null
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.inabit.com/api-reference/remote-approver-app/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.