# Webhooks

The webhooks API allows you to register a webhook in a specific node, which will send a payload to a predefined target when certain conditions are met. Webhooks ensure that you do not need to poll the public API periodically and are a robust way to stay up-to-date with the blockchain state.

# Authentication

To communicate with the Webhooks API, you will need to provide the token you configured on your node through the Authorization header. Authenticating with an invalid token will return 401 Unauthorized.

# Headers

# 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": 1,
            "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": 1,
        "event": "block.forged",
        "target": "https://httpbin.org/post",
        "enabled": true,
        "conditions": [
            {
                "key": "generatorPublicKey",
                "condition": "eq",
                "value": "032fcfd19f0e095bf46bd3ada87e283720c405249b1be1a70bad1d5f20095a8515"
            }
        ]
    }
}

# Create a Webhook

Before creating a webhook, ensure you have a backend service running which exposes the target. Some example setups are listed here. 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.

# Endpoint

POST /api/webhooks

# Body Parameters

# Response

{
    "data": {
        "id": 1,
        "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

{}

# 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

{}