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¶

GET /api/webhooks

Query Parameters¶

Response¶

{
  "meta": {
    "count": 29,
    "pageCount": 1,
    "totalCount": 29,
    "next": null,
    "previous": null,
    "self": "/api/v2/webhooks?page=1&limit=100",
    "first": "/api/v2/webhooks?page=1&limit=100",
    "last": "/api/v2/webhooks?page=1&limit=100"
  },
  "data": [
    {
      "id": "4b255244-a535-4aca-aa92-9ff9e02c98dd",
      "event": "block.forged",
      "target": "https://httpbin.org/post",
      "enabled": true,
      "conditions": [
        {
          "key": "generatorPublicKey",
          "condition": "eq",
          "value": "032fcfd19f0e095bf46bd3ada87e283720c405249b1be1a70bad1d5f20095a8515"
        }
      ]
    }
  ]
}

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¶

GET /api/webhooks/{id}

Path Parameters¶

Response¶

{
  "data": {
    "id": "4b255244-a535-4aca-aa92-9ff9e02c98dd",
    "event": "block.forged",
    "target": "https://httpbin.org/post",
    "enabled": true,
    "conditions": [
      {
        "key": "generatorPublicKey",
        "condition": "eq",
        "value": "032fcfd19f0e095bf46bd3ada87e283720c405249b1be1a70bad1d5f20095a8515"
      }
    ]
  }
}

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¶

POST /api/webhooks

Body Parameters¶

Response¶

{
  "data": {
    "id": "4b255244-a535-4aca-aa92-9ff9e02c98dd",
    "event": "block.forged",
    "target": "https://httpbin.org/post",
    "token": "7e66949f67b36c34a05eeb3a866957b3f1b6f8947fb215500b78e5091d4e484a",
    "enabled": true,
    "conditions": [
      {
        "key": "generatorPublicKey",
        "condition": "eq",
        "value": "032fcfd19f0e095bf46bd3ada87e283720c405249b1be1a70bad1d5f20095a8515"
      }
    ]
  }
}

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¶

PUT /api/webhooks/{id}

Path parameters¶

Body parameters¶

Response¶

HTTP/1.1 204 No Content
{}

Delete a webhook¶

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

Endpoint¶

DELETE /api/webhooks/{id}

Path parameters¶

Response¶

HTTP/1.1 204 No Content
{}