Home

Webhook Notifications

Listen for events on your Openfort account so your integration can automatically trigger reactions.

What is a webhook?#

Openfort uses webhooks to push real-time notifications to you about your transactions. All webhooks use HTTPS and deliver a JSON payload that can be used by your application. You can use webhook feeds to do things like:

  • Granting users a game item when a transaction is confirmed.
  • Store all transaction events in your own database for custom reporting/retention

Steps to receive webhooks#

You can start receiving real-time events in your app using the steps:

  1. Create a local endpoint to receive requests
  2. Register your development webhook endpoint
  3. Test that your webhook endpoint is working properly
  4. Register your production webhook endpoint

Webhook object#

The webhook object contains the following fields:


_10
{
_10
"data": {
_10
"id": "tin_c502d628-5bb3-42f2-b8f5-62ba4d71df3a",
_10
"createdAt": 1689869074,
_10
"object": "transactionIntent",
_10
"etc":"..."
_10
},
_10
"type": "transaction_intent.succeeded",
_10
"date": 1689869074
_10
}

Where the type will be one of the following:

  • transaction_intent.succeeded: The transaction intent has arrived on-chain and is confirmed.
  • transaction_intent.failed: The transaction intent has arrived on-chain and is reverted.

And the data will be a transaction intent object.

1. Create a local endpoint to receive requests#

In your local application, create a new route that can accept POST requests.

server.ts

_29
app.post(
_29
'/webhook',
_29
express.raw({ type: 'application/json' }),
_29
async (req: Request, _res: Response) => {
_29
const openfort = new Openfort('OPENFORT_SECRET_KEY')
_29
try {
_29
const event = await openfort.constructWebhookEvent(
_29
req.body.toString(),
_29
req.headers['openfort-signature']
_29
)
_29
switch (event.type) {
_29
case "transaction_intent.succeeded":
_29
console.log(`TransactionIntent ID: ${event.data.id}`)
_29
break
_29
case "transaction_intent.failed":
_29
console.log(`TransactionIntent ID: ${event.data.id}`)
_29
break
_29
default:
_29
console.log(`Unhandled event type ${event.type}`);
_29
}
_29
} catch (e) {
_29
console.error((e as Error).message)
_29
}
_29
}
_29
)
_29
_29
app.listen(port, () => {
_29
console.info(`Server is running on http://localhost:${port}`)
_29
})

2. Register your development webhook endpoint#

Register your publicly accessible HTTPS URL in the Openfort dashboard.

tip

You can create a tunnel to your localhost server using a tool like ngrok. For example: https://8733-191-204-177-89.sa.ngrok.io/webhooks

transaction_intent-sign

3. Test that your webhook endpoint is working properly#

Send a few test transactions to check that your webhook endpoint is receiving the events.

You can specify the number of block confirmations you want to wait before getting notified of a transaction making it on chain. The default is 0 (i.e. as soon as the transaction arrives on chain).

To do so, you need to include the confirmationBlocks body parameter when creating the transaction intent.

transaction_intent-sign

4. Register your production webhook endpoint#

Once your webhook endpoint is deployed to production, register the new webhook url in the dashboard.