Webhooks

You are here:
< Back

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

NameTypeDescriptionRequired
AuthorizationstringThe webhook token defined in the node configuration.

List all webhooks

Endpoint

GET /api/webhooks

Query Parameters

NameTypeDescriptionRequired
pageintThe number of the page that will be returned.
limitintThe 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

NameTypeDescriptionRequired
idstringThe 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

NameTypeDescriptionRequired
eventstringThe name of the event to be listened for.
targetstringThe target url for the HTTP payload.
enabledstringThe value to enable or disable the webhook.
conditionsarrayThe 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

EventDescriptionImplemented
block.appliedFires when a block is saved
block.forgedFires when a block is forged
block.revertedFires when a block is removed from the database (e.g. on a rollback)
delegate.registeredFires when a new delegate is registered
delegate.resignedFires when a delegate resigns
forger.failedFires when the forger module fails to start
forger.missingFires when it is detected that the forger module isn’t running
forger.startedFires when the forger module forges a new block
peer.addedFires when a peer is added
peer.removedFires when a peer is removed
round.createdFires when a new round is created and saved to the database
state:started
transaction.appliedFires when a transaction is saved
transaction.expiredFires when an unconfirmed transaction expires
transaction.forgedFires when a transaction is forged by a delegate
transaction.revertedFires when a transaction is removed from the database
wallet.savedFires when a wallet is updated (e.g. its balance changed, voted etc)
wallet.created.coldFires when a wallet that never existed before is saved (e.g. received its first tx)

Conditions

ConditionDescription
betweenCheck if the given value is between min and max
containsCheck if A contains B
eqCheck if A equals B
falsyCheck if the given value is false
gtCheck if A is greater than B
gteCheck if A is greater than or equal to B
ltCheck if A is lesser than B
lteCheck if A is lesser than or equal to B
neCheck if A does not equal B
not-betweenCheck if the given value is not between min and max
regexpCheck if the given value matches
truthyCheck if the given value is true

Update a webhook

Endpoint

PUT /api/webhooks/{id}

Path Parameters

NameTypeDescriptionRequired
idstringThe identifier of the webhook to be updated.

Body Parameters

NameTypeDescriptionRequired
eventstringThe name of the event to be listened for.
targetstringThe target url for the HTTP payload.
enabledstringThe value to enable or disable the webhook.
conditionsarrayThe list of conditions required to trigger the webhook.

Response

{}

Delete a webhook

Endpoint

DELETE /api/webhooks/{id}

Path Parameters

NameTypeDescriptionRequired
idstringThe identifier of the webhook to be deleted.

Response

{}
Last Updated On January 14, 2019