Introduction

By setting up webhooks, you can receive real-time notifications about significant events directly to your specified endpoint, enabling you to respond promptly and effectively to validator marketplace activities.

📘

What is a Webhook?

A webhook is an HTTP callback, an automated message sent from apps when something happens. They have a message—or payload—and are sent to a unique URL, essentially an app’s phone number or address.

Using Webhooks on Northstake validator marketplace

Northstake's webhook system is designed to notify you of various events occurring within the RFQ Marketplace. These events can range from new RFQ postings, bid receipts, bid acceptances, to escrow events and more. Utilizing webhooks ensures that you stay updated without having to poll the API continuously.

Key Concepts

• Event Subscription: You register a webhook to subscribe to specific types of events. Each type of event has a corresponding payload structure that will be POSTed to your webhook URL.
• Security: To ensure that the received webhooks are from Northstake, each POST request will include a Bearer token in the Authorization header. It's crucial to validate this token upon receipt.
• Reactivity: Webhooks enable your systems to react to events in real-time, which is essential for timely actions within the RFQ Marketplace, like posting or responding to RFQs.

🔥

Some features require you to have properly registered webhooks

In order to ensure that the Northstake platform operates as swiftly and efficiently as possible, we require our users to have the proper webhook registrations in place before performing certain actions, such as posting or responding to RFQs on the validator marketplace.

For an example of how to ensure that you're properly set up for posting RFQs to the validator marketplace see this recipe:

📃

(SDK) Submitting an RFQ to the validator marketplace

Open Recipe

Setting Up Webhooks

Step 1: Register Your Webhook

To begin receiving webhook notifications, you need to register your webhook with the Northstake API. Here is an example request to register a webhook:

import {NorthstakeAp} from @northstake/northstakeapi

const api = new NorthstakeApi('apiKey', 'privateKey')
                                     
const webhook: WebhookRegistration = {
    url: '<https://your.webhook.url>',
    eventType: 'RFQAvailable'
    secret: 'your-secret',
  }

await api.validatorMarketplaceWebhooks.registerWebhook(webhook)

POST /validatorMarketplace/webhooks
Content-Type: application/json

{
  "url": "https://your.webhook.url",
  "eventType": "RFQAvailable",
  "secret": "yourSecretToken"
}

Supported Event Types

• RFQAvailable: Notifies when a new RFQ document becomes available.
• RFQBidReceived: Triggered when a new bid is received.
• RFQBidAccepted: Triggered when a bid is accepted.
• RFQEscrowEvent: Notifies when an escrow payment is made.
• RFQReceivedTransferProposal : Notifies an RFQ seller of a new transfer proposal on their RFQ
• RFQValidatorWithdrawalChange: Notifies RFQ buyer when a validator or set of validators has had their withdrawal addresses changed to the buyer's address
• RFQEscrowReleased: Notifies when escrow funds are released.
• RFQValidatorExited Notifies the owner whenever a validator exits the ethereum network

Step 2: Handle Incoming Webhooks

When an event occurs, Northstake will send a POST request to your registered URL with the event's data. The header will contain the Authorization token that you must validate to confirm the request's authenticity.

Example Payload

{  
  "document_id": "rfq123",  
  "event": "RFQAvailable",  
  "details": {  
    "id": "rfq123",  
    "validators": [  
      {  
        "validator_index": 1,  
        "balance": 32,  
        "exit_estimates": [  
          {  
            "estimated_exit_time": "2025-03-01T12:00:00Z",  
            "timestamp": "2024-03-01T12:00:00Z"  
          }  
        ]  
      }  
    ],  
    "total_balance": 32,  
    "payment_address": "0xabcd",  
    "estimated_exit_transaction_deadline": "2025-03-01T12:00:00Z"  
  }  
}

See all payload examples in the API reference

Security: Validating Webhooks

Important: All webhook requests include a Bearer token in the Authorization header. Ensure that you validate this token with each request to confirm that it's from a trusted source. The token you receive should match the secret you provided when registering the webhook.

🔐

Have your webhook endpoints validate the bearer token

It is your responsibility to make sure that your HTTP endpoints receiving POSTs from Northstake via your webhook registrations, are properly secured.

Always ensure that any request received by your webhook endpoints are properly set up to validate the headers and bearer tokens in a safe and adequate manner.

Managing Your Webhooks

Listing Your Registered Webhooks

To retrieve a list of all webhooks you have currently registered, you can use the following Northstake SDK code snippet:

import { NorthstakeApi } from '@northstake/northstakeapi';

const api = new NorthstakeApi('apiKey', 'privateKey');

const {body: webhooks}  = await api.validatorMarketplaceWebhooks.listRegisteredWebhooks();

for (const webhook of webhooks) {
  console.log(`
    Webhook ID: ${webhook.id}
    Webhook URL: ${webhook.url}
    Webhook Event Type: ${webhook.eventType}
  `);
}

Unsubscribing from Events

Removing Your Webhooks

If you no longer need to receive updates for certain events, you can remove the registered webhook using its unique identifier. This action stops all notifications from being dispatched to your designated endpoint.

SDK Example

import { NorthstakeApi } from '@northstake/northstakeapi';

const api = new NorthstakeApi('apiKey', 'privateKey');

// Replace 'webhook-id' with your actual webhook ID
await api.validatorMarketplaceWebhooks.deleteWebhook('webhook-id');

Conclusion

Webhooks provide a powerful way to integrate and automate reactions within the Northstake platform, especially within the RFQ Marketplace. By following this guide, you can set up, secure, and manage your webhooks effectively, ensuring that you remain responsive and up-to-date with events that matter most to your operations.