Webhooks

WARNING

All HTTP requests have to be sent with the Content-Type: application/json header. If the header is not present it will result in malformed responses or request rejections.

Authentication

In order 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

Name Type Description Required
Authorization string The webhook token defined in the node configuration.

List all webhooks

Endpoint

GET /api/webhooks

Query Parameters

Name Type Description Required
page int The number of the page that will be returned.
limit int The number of resources per page.

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

Endpoint

GET /api/webhooks/{id}

Path Parameters

Name Type Description Required
id string The identifier of the webhook to be retrieved.

Response

{
    "data": {
        "id": 1,
        "event": "block.forged",
        "target": "https://httpbin.org/post",
        "enabled": true,
        "conditions": [
            {
                "key": "generatorPublicKey",
                "condition": "eq",
                "value": "032fcfd19f0e095bf46bd3ada87e283720c405249b1be1a70bad1d5f20095a8515"
            }
        ]
    }
}

Create a webhook

Endpoint

POST /api/webhooks

Body Parameters

Name Type Description Required
event string The name of the event to be listened for.
target string The target url for the HTTP payload.
enabled string The value to enable or disable the webhook.
conditions array The list of conditions required to trigger the webhook.

Response

{
    "data": {
        "id": 1,
        "event": "block.forged",
        "target": "https://httpbin.org/post",
        "token": "7e66949f67b36c34a05eeb3a866957b3f1b6f8947fb215500b78e5091d4e484a",
        "enabled": true,
        "conditions": [
            {
                "key": "generatorPublicKey",
                "condition": "eq",
                "value": "032fcfd19f0e095bf46bd3ada87e283720c405249b1be1a70bad1d5f20095a8515"
            }
        ]
    }
}

Events

Event Description Implemented
block.applied Fires when a block is saved
block.forged Fires when a block is forged
block.reverted Fires when a block is removed from the database (e.g. on a rollback)
delegate.registered Fires when a new delegate is registered
delegate.resigned Fires when a delegate resigns
forger.failed Fires when the forger module fails to start
forger.missing Fires when it is detected that the forger module isn't running
forger.started Fires when the forger module forges a new block
peer.added Fires when a peer is added
peer.removed Fires when a peer is removed
round.created Fires when a new round is created and saved to the database
state:started
transaction.applied Fires when a transaction is saved
transaction.expired Fires when an unconfirmed transaction expires
transaction.forged Fires when a transaction is forged by a delegate
transaction.reverted Fires when a transaction is removed from the database
wallet.saved Fires when a wallet is updated (e.g. its balance changed, voted etc)
wallet.created.cold Fires when a wallet that never existed before is saved (e.g. received its first tx)

Conditions

Condition Description
between Check if the given value is between min and max
contains Check if A contains B
eq Check if A equals B
falsy Check if the given value is false
gt Check if A is greater than B
gte Check if A is greater than or equal to B
lt Check if A is lesser than B
lte Check if A is lesser than or equal to B
ne Check if A does not equal B
not-between Check if the given value is not between min and max
regexp Check if the given value matches
truthy Check if the given value is true

Update a webhook

Endpoint

PUT /api/webhooks/{id}

Path Parameters

Name Type Description Required
id string The identifier of the webhook to be updated.

Body Parameters

Name Type Description Required
event string The name of the event to be listened for.
target string The target url for the HTTP payload.
enabled string The value to enable or disable the webhook.
conditions array The list of conditions required to trigger the webhook.

Response

{}

Delete a webhook

Endpoint

DELETE /api/webhooks/{id}

Path Parameters

Name Type Description Required
id string The identifier of the webhook to be deleted.

Response

{}
Last Updated: 12/30/2018, 12:58:44 AM