#Endpoints

#List All Webhooks

The webhooks resource returns all enabled and disabled webhooks. There is thus no need to store all active webhooks client side; as the node maintains a register for you.

#Endpoint

1GET /api/webhooks

#Query Parameters

#Response

 1{
 2  "meta": {
 3    "count": 29,
 4    "pageCount": 1,
 5    "totalCount": 29,
 6    "next": null,
 7    "previous": null,
 8    "self": "/api/v2/webhooks?page=1&limit=100",
 9    "first": "/api/v2/webhooks?page=1&limit=100",
10    "last": "/api/v2/webhooks?page=1&limit=100"
11  },
12  "data": [
13    {
14      "id": "4b255244-a535-4aca-aa92-9ff9e02c98dd",
15      "event": "block.forged",
16      "target": "https://httpbin.org/post",
17      "enabled": true,
18      "conditions": [
19        {
20          "key": "generatorPublicKey",
21          "condition": "eq",
22          "value": "032fcfd19f0e095bf46bd3ada87e283720c405249b1be1a70bad1d5f20095a8515"
23        }
24      ]
25    }
26  ]
27}

#Retrieve a Webhook

It is possible to query for a specific webhook by ID, which has to be saved client-side or obtained from another API call.

#Endpoint

1GET /api/webhooks/{id}

#Path Parameters

#Response

 1{
 2  "data": {
 3    "id": "4b255244-a535-4aca-aa92-9ff9e02c98dd",
 4    "event": "block.forged",
 5    "target": "https://httpbin.org/post",
 6    "enabled": true,
 7    "conditions": [
 8      {
 9        "key": "generatorPublicKey",
10        "condition": "eq",
11        "value": "032fcfd19f0e095bf46bd3ada87e283720c405249b1be1a70bad1d5f20095a8515"
12      }
13    ]
14  }
15}

#Create a Webhook

It is recommended to have a backend service running that will handle your webhook calls, as you’ll have to provide a target value when creating the webhook. To give you an idea of how this works, we created a couple of example setups that you can use or get inspiration from. A webhook may be triggered by multiple conditions; as long as one of the conditions evaluates to true, the webhook will fire.

The returned token should be saved and used to validate the webhook origin. It is a secret value which should not be shared. For extra security, whitelist the IP of the node with your target service, ensuring other parties are not able to post webhook payloads.

The conditions lists consists of an array of objects, with the following properties:

• key: the key used on the object that is passed along with the specified event
• condition: a condition used to check the value against
• value: (Optional) a value used to check the key against. This is not needed for the falsy and truthy conditions. In case of between and not-between, you’ll have to provide an object like this: "value": { "min": "someValue", "max": "someValue" }

#Endpoint

1POST /api/webhooks

#Body Parameters

#Response

 1{
 2  "data": {
 3    "id": "4b255244-a535-4aca-aa92-9ff9e02c98dd",
 4    "event": "block.forged",
 5    "target": "https://httpbin.org/post",
 6    "token": "7e66949f67b36c34a05eeb3a866957b3f1b6f8947fb215500b78e5091d4e484a",
 7    "enabled": true,
 8    "conditions": [
 9      {
10        "key": "generatorPublicKey",
11        "condition": "eq",
12        "value": "032fcfd19f0e095bf46bd3ada87e283720c405249b1be1a70bad1d5f20095a8515"
13      }
14    ]
15  }
16}

#Events

#Conditions

#Update a Webhook

Existing webhooks may be updated. Note that this is the equivalent of deleting and creating a webhook; but retaining the same token. If you are often updating and creating webhooks; consider deleting and creating new webhooks instead of updating to rotate your validation token often.

#Endpoint

1PUT /api/webhooks/{id}

#Path Parameters

#Body Parameters

#Response

1HTTP/1.1 204 No Content
2{}

#Delete a Webhook

A webhook may be deleted by ID. Delete unused webhooks to save machine resources.

#Endpoint

1DELETE /api/webhooks/{id}

#Path Parameters

#Response

1HTTP/1.1 204 No Content
2{}