> For the complete documentation index, see [llms.txt](https://docs.inabit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.inabit.com/api-reference/remote-approver-app/webhooks.md).

# 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 %}