Webhooks

In this guide, we will look at how to register and utilize webhooks to integrate your dApp with SELF. With webhooks, your dApp can configure event listeners to detect when something happens in SELF, such as someone sending a message or setting a highscore in a game. As an alternative its possible to relay web3 events so it can be processed in the customers dApp.

Registering webhooks

To register a new webhook, you need to have a URL in your dApp that SELF can call. As an alternative we planned to include the option of registerering a new webhook directly from the SELF API dashboard API settings.

Once done, whenever something of interest happens in your dApp, a webhook is fired off by SELF.

Consuming webhooks

When your dApp receives a webhook request from SELF, you check the type attribute to see which event caused it. The first part of the event type will tell you the payload type, like when a game has ended, or a message is received, etc.

Example webhook payload

{
  "id": "a056V7R7NmNRjl70",
  "type": "game.score",
  "action": "game.update",
  "payload": {
    "id": "WAz8eIbvDR60rouK",
    "player" : "superman",
    "stage" : 6,
    "score" : 12500,
    // ...
  }
}

In the example above, a record was updated, and the payload type is a game.score.

See all event types

Event types

These are just some examples of events SELF API-server can process;

Name
game.created
Type
Description
A new game was created.
Name
game.updated
Type
Description
An existing game was updated.
Name
game.deleted
Type
Description
A game was successfully deleted.
Name
selfname.created
Type
Description
A new selfname was created.
Name
selfname.updated
Type
Description
An existing selfname was updated.
Name
selfname.deleted
Type
Description
A selfname was successfully deleted.
Name
message.created
Type
Description
A new message was created.
Name
message.updated
Type
Description
An existing message was updated.
Name
message.deleted
Type
Description
A message was successfully deleted.

Example payload

{
  "id": "a056V7R7NmNRjl70",
  "type": "metadata.updated",
  "payload": {
    "id": "SIuAFUNKdSYHZF2w",
    "self_hash": "xgQQXg3hrtjh7AvZ",
    "game": {
      "id": "WAz8eIbvDR60rouK",
      "username": "kevin_wm_mcallister",
      "avatar_url": "ipc/...<hidden><hashed>",
      "created_at": 692233200
    },
    "field": "personal_msg",
    "value": "I’m always traveling and I hate meetings. ",
    "attachments": [],
    "created_at": 692233200,
    "updated_at": 692233200
  }
}

Security

Each webhook request contains a header named x-SELF-signature that can hold both public or private keys. We can, for instance, have the key with a timestamp and pass this timestamp as a parameter as well as to decode the encrypted payload.

Webhooks provide unlimited solutions resulting in workflows and are still in the early stages of the SELF development plan. We constantly evaluate the alternatives of webhooks with our clients.

NFT Contract Events

For a general understanding, most web3 Smart Contracts contain events that SELF API-server can relay to web2 dApps. Below is an example list of the 'Events' section of a Smart Contract.

NFT Contract events

{

//=================Events===================
event NameRegistered(address indexed owner, string name, uint tokenId);
event MetadataUpdated(uint256 indexed tokenId, string metadata);
event PriceUpdated(uint256 indexed length, uint256 indexed price);
event SelfTokenUpdated(address indexed newSelfToken);
event CollectedSelfForwarded(address indexed receiver, uint256 amount);
event AgentAdded(address indexed agent, uint commission);
event AgentUpdated(address indexed agent, uint commission);
event AgentRemoved(address indexed agent);
event NameReserved(string indexed name);
event NameUnreserved(string indexed name);
}