Triggers

A trigger is the SendBlocks way of describing some occurrence on the blockchain that invokes the function in question. When a function is invoked, it receives the relevant context and data objects of the occurrence that triggered it.

Every trigger has a type, as well as type-specific parameters. It's important to note that the SendBlocks engine matches every occurrence of the trigger on its function’s configured blockchain, which may be found in an external or an internal transaction, or even within the input or output of a log or transaction.

Here is an example of a trigger definition on a function, see Create Function or Update Function in the API reference for more complete examples:

{
  "function_name": "my_function",
  "description": "This function forwards its context and data objects to the webhook",
  "chain_id": "CHAIN_ETH_MAINNET",
  "webhook_id": "12345678-1234-1234-1234-123456789abc",
  "function_code": "ZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIHRyaWdnZXJIYW5kbGVyKGNvbnRleHQsIGRhdGEpIHsKICAgIHJldHVybiB7ImNvbnRleHQiOiBjb250ZXh0LCAiZGF0YSI6ZGF0YX07Cn0=",
  "triggers": [
    {
      "type": "TRIGGER_TYPE_ADDRESS",
      "address": "0x283af0b28c62c092c9727f1ee09c02ca627eb7f5"
    }
  ]
}

In the sections that follow we will introduce the various trigger types that we currently support.

The format of the trigger details that will be provided to your functions via the context object is described here.

Address Triggers

An address trigger will fire when the specified address shows up somewhere in a blockchain transaction.

Here’s an example of a trigger set on ENS: Old ETH Registrar Controller, the ENS deployer address:

{
    "type": "TRIGGER_TYPE_ADDRESS",
    "address": "0x283af0b28c62c092c9727f1ee09c02ca627eb7f5"
}

In the above example, the address trigger will fire regardless of where in the on-chain data the address was seen.

Address triggers can fire from a variety of locations, some of which may be chain-specific. When configuring an address trigger, you can specify which locations are of interest, and filter accordingly.

For example, if we only wanted the above trigger to fire when the address in question is found in the to field of a trace, we would configure the trigger as follows:

{
    "type": "TRIGGER_TYPE_ADDRESS",
    "address": "0x283af0b28c62c092c9727f1ee09c02ca627eb7f5",
    "locations": [
        "trace_to"
    ]
}

When no locations are specified, all locations will be examined by default. We recommend making use of the location filtering to avoid unnecessary invocations, but in many cases it may be preferable to perform filtering within the function code itself. See Trigger Object for a detailed breakdown of what your functions can expect to receive.

Chains and Locations

As mentioned above, some locations are particular to certain chains. A list of supported blockchains can be found under Supported Blockchains.

At the time of writing, most locations can be used to filter address triggers on all of our supported chains, but event_attribute is an attribute only available on Cosmos Osmosis.

Event Triggers

An event trigger will fire when the specified event signature appears in a blockchain transaction’s event logs.

Here’s an example of a trigger set on OwnershipTransferred events:

{
    "type": "TRIGGER_TYPE_EVENT",
    "event": "0x8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0"
}

In the above example, the event trigger will fire whenever we encounter an event on the chain with a matching signature.

Cosmos Osmosis Events

For Cosmos Osmosis events, the event signature would be in the form of an action, eg. /ibc.core.client.v1.MsgUpdateClient, or of a message's event type, eg. update_client. Take a look at transaction 0B6327F3A334745EFEF9DB9231DFF62E0A8FCCB6A995E6ED368B630C1BFF09B6 for an example of a transaction that would trigger functions listening for either of the above examples.

Specifying an Event Emitter

Many contracts generate events with the same signatures. When configuring an event trigger, you can specify which event emitter’s events you’re interested in by providing its address.

For example, if we only wanted the above trigger to fire on a Chainlink OwnershipTransferred event, we would configure the trigger as follows:

{
    "type": "TRIGGER_TYPE_EVENT",
    "address": "0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419",
    "event": "0x8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0"
}

Function Triggers

A function trigger will fire when a contract’s internal function matching the specified function signature is called.

Here’s an example of a trigger set on the function internalCall_greet(), which calls the greet() function on a different contract:

{
    "type": "TRIGGER_TYPE_FUNCTION",
    "function": "0xbeabacc8"
}

(You can find an example of a contract that includes this function here)

New Block Triggers

A new block trigger will fire whenever a new block on the chain is processed.

{
    "type": "TRIGGER_TYPE_NEW_BLOCK"
}

New Contract Triggers

A new contract trigger will fire whenever a new contract is published on the chain.

{
    "type": "TRIGGER_TYPE_NEW_CONTRACT"
}

Storage Triggers

Storage triggers are a bit more complicated to explain, so they get their own pages. See EVM Storage and the Storage Trigger Example for more details.