Skip to content

Webhooks

Webhooks are a feature that allows systems to be called upon across the internet based on the emission of a blockchain event that meets some criteria.

You can listen to transactions via webhooks using the Sequence Indexer by registering an endpoint or removing it after it's no longer required.

To begin, direct yourself to the Sequence Builder and follow this walkthrough for Public API Access Key and this walkthrough for a Secret API Access Key, both required for using the Sequence Indexer Webhooks.

Function

  1. Register a Webhook Listener
  2. Remove a Webhook Listener

Service response

  1. Webhook Listener Response

Examples

  1. Listen to All Mints of a Contract
  2. Listen to Mints of a Specific Token ID
  3. Listen to Event Topic Hashes for a Contract
  4. Listen to Marketplace Request Creation

1. Register a Webhook Listener

Our filters allow you to listen to events with a particular contract address and/or account address, specific token ids, events, or topic hashes.

Sequence Indexer AddWebhookListener Method:

  • Request: POST /rpc/Indexer/AddWebhookListener
  • Content-Type: application/json
  • Body (in JSON):
    • url (string) -- the URL to send the webhook to
    • filters (object) -- an array of filters
      • contractAddresses ([]string) -- a ERC20 / ERC721 / ERC1155 contract address
      • accounts ([]string) -- wallet addresses
      • events ([]string) -- the string of the event (e.g. "Transfer(address,address,uint256)")
      • topicHashes ([]string) -- a hash of the of the event (e.g. ethers.utils.id("Transfer(address,address,uint256)"))
      • tokenIDs ([]int) optional -- an array of token ids

One of contractAddresses or accounts must be provided in the filter.

Example: AddWebhookListener
cURL
curl -X POST -H "Content-Type: application/json" -H "X-Access-Key: <project_access_key>" -H "Authorization: BEARER <secret_API_key>", "filters": {"contractAddresses":["0x631998e91476DA5B870D741192fc5Cbc55F5a52E"]}}'

Now you can listen to events on the blockchain with your webhook.

2. Remove a Webhook Listener

If you need to clean up your webhook listeners, you can submit requests to remove the listener based on listener id and projectId

Sequence Indexer RemoveWebhookListener Method:

  • Request: POST /rpc/Indexer/RemoveWebhookListener
  • Content-Type: application/json
  • Body (in JSON):
    • id (string) -- the id of the listener returned when registering the response.listener.id
    • projectId (string) -- the project id the JWT token was obtained from

Example: RemoveWebhookListener

In the following examples you'll need to update the id of the webhook listener, returned in the AddWebhookListener

cURL
curl -X POST -H "Content-Type: application/json" -H "X-Access-Key: <project_access_key>" -H "Authorization: BEARER <secret_API_key>" https://polygon-indexer.sequence.app/rpc/Indexer/RemoveWebhookListener -d '{ "id": <listener_id>, "projectId": 25906}'

Webhook Listener Response

Upon webhook listener response, an object is returned in the following structure

  • Response (in JSON):
    • id (i32) -- the id of the response
    • type (string), -- the type of event (i.e. BLOCK_ADDED)
    • blockNumber (i32) -- the block number from the blockchain for when the event occured
    • blockHash (string) -- the hash of the block for the transaction
    • parentBlockHash (i32) -- the hash of the parent block
    • contractAddress (string) -- the contract address from where the event came from
    • contractType (string) -- the type of contract (e.g. ERC20, ERC721, ERC1155, etc.)
    • txnHash (string) -- the transaction hash of the event
    • txnIndex (i32) -- the index of the transaction in the blockchain block
    • txnData (object) -- the transaction data of who sent to who
      • value (string) -- the value of the transaction
      • from (string) -- the originator of the transaction, if there is a value
      • to (string) -- the destination address of the transaction, if there is a value
    • txnLogIndex (string) -- the log index in the transaction
    • logDataType (string) -- the type of log event (e.g. TOKEN_TRANSFER)
    • Log (object) -- the emitted event data

Examples

Provided are a few additional TypeScript examples:

1. Listen to All Mints of a Collectible Contract

If you want to get all mints and transfers of a contract

cURL
curl -X POST -H "Content-Type: application/json" -H "X-Access-Key: <project_access_key>" -H "Authorization: BEARER <secret_API_key>", "filters": {"contractAddresses":["0x9bec34c1f7098e278afd48fedcf13355b854364a"]}}'

2. Listen to a Specific Token ID for an ERC1155

If you want to get all mints of a specific token ID for an ERC1155

cURL
curl -X POST -H "Content-Type: application/json" -H "X-Access-Key: <project_access_key>" -H "Authorization: BEARER <secret_API_key>", "filters": {"contractAddresses":["0x9bec34c1f7098e278afd48fedcf13355b854364a"], tokenIDs: ['1237']}}'

Custom Return Data Types Glossary

TransferEvent (object)
FieldTypeDescription
operatorstringthe address of the operator
fromstringthe address of who the transaction came from
tostringthe address of who the transaction is for
tokenIDs[]i32an array of the token IDs transferred
amounts[]i32an array of the amounts of tokens transferred
OrderbookRequestCreated (object)
FieldTypeDescription
requestIdi32the request id as an incremented value of the order
creatorstringthe user address who created the order
tokenContractstringthe token contract of that the order is for
tokenIdi32the token identifier
isListingbooleanwhether the order is to list (true) or offer orders (false)
quantityi32the number of tokens the order is for
currencystringthe currency address of the order
pricePerTokeni32the price per token for the order
expiryi32the expiry of when the order is no longer valid
rawLogthe raw log
OrderbookRequestAccepted (object)
FieldTypeDescription
requestIdi32the request id as an incremented value of the order
buyerstringthe user address for who purchased the order
tokenContractstringthe token contract of that the order is for
receiverstringthe user address for who who recieves the token
quantityi32the number of tokens
quantityRemainingi32the remaining number of tokens left in the order
rawLogthe raw log
OrderbookRequestCancelled (object)
FieldTypeDescription
requestIdi32the request id as an incremented value of the order
tokenContractstringthe token contract of that the order is for
rawLogthe raw log
Log (object)
FieldTypeDescription
addressstringthe address from which the event came from
topics[]stringthe topic event hashes emitted in the logs
data[]stringdata
blockNumberi64the hex of the block number
txHashstringthe transaction hash from the blockchain
txIndexi32the index of the transaction in the blockchain block in hex
blockHashstringthe hash of the block for the transaction
indexi32the log index in the transaction
removedbooleanif the log of the event has been removed based on reorganizations