Alert Webhooks

Get realtime wallet notifications for your Portal clients.

What's an alert webhook?

Alert webhooks can send you realtime wallet notifications for your clients. For example, they can be useful for receiving notifications when your clients receive or send EVM transactions. Alert webhooks are easily configured in the Portal Admin Dashboard. If you don't see "Alert Webhooks" in the Portal Admin Dashboard, reach out to our team and we can enable the feature for you.

Configuring alert webhooks

1. Reach out to our support team and we can enable alert webhooks for your organization.

2. Navigate to "Settings" > "Alert Webhooks" in the Portal Admin Dashboard and click "New +".

   

   Click "New +" in the "Alert Webhooks" section.
3. Enter your alert webhook URL:

   

   Enter your webhook URL, select the events, and click "Create".
4. Select the events you want to receive (e.g. EIP-155 Inbound/Outbound Transactions).

5. Save your configuration.

Take note of the IP addresses listed on this modal. You can add them to your allowlist to ensure you're only accepting requests from Portal.

Events

Handling EIP-155 Inbound/Outbound Transaction events

Immediately after configuring the alert webhook with EIP-155 Inbound/Outbound Transaction selected as an event, Portal starts to listen for any inbound/outbound EIP-155 transactions for your clients that have an EIP-155 address. From then on when you create a new client with an EIP-155 address, Portal will notify you of their on-chain transactions.

When a transaction occurs, you'll receive a POST request to your configured alert webhook URL with a request body that contains the alert webhook event's details.

Below is an example of an inbound ETH transfer to a Portal wallet:

POST https://example.com/your-alert-webhooks/1/events

Headers:

Name	Type	Description
Content-Type*	String	application/json
X-WEBHOOK-SECRET*	String	You can find the alert webhook secret in the Portal Admin Dashboard on the "Settings" page under the "Alert Webhooks" section.

Request body (example):

{
  "data": [
    {
      "amount": "0.01",
      "assetType": "NATIVE_TOKEN",
      "chainId": "eip155:11155111",
      "chainName": "sepolia",
      "direction": "INBOUND",
      "from": "0xdfd8302f44727a6348f702ff7b594f127de3a902", // External wallet
      "to": "0xd66a7df2e6081e347bffb30ed1f4a03014b1f847", // The Portal client's EIP-155 address
      "tokenSymbol": "ETH",
      "metadata": {
        "approvalSpender": null,
        "blockNumber": "7319953",
        "confirmed": true,
        "fee": {
          "amount": "0.000167770484721",
          "decimals": 18,
          "rawAmount": "167770484721000",
          "tokenSymbol": "ETH"
        },
        "nftTokenId": null,
        "rawAmount": "10000000000000000",
        "sentAt": "2024-12-20T19:25:24.000Z",
        "tokenAddress": null,
        "tokenDecimals": 18,
        "tokenName": "ETH",
        "transactionHash": "0xfca020f709ef8117f3d332c6644db38a41d1e6b47c729167c2c0cc5b05199141",
        "triggeredBy": "0xd66a7df2e6081e347bffb30ed1f4a03014b1f847", // The Portal client's EIP-155 address
        "userOperationHash": null
      }
    }
  ],
  "metadata": {
    "custodianId": "custodianId",
    "environmentId": "environmentId"
  },
  "type": "EIP_155_TX_V1"
}

Security

Here are a few considerations to ensure your alert webhooks are implemented securely:

• Alert webhook URLs must use HTTPS.

• Verify that each alert webhook request has the expected X-WEBHOOK-SECRET header value. You can find the secret for your alert webhook in the Portal Admin Dashboard.

• Restricting requests on your alert webhook server to only those from Portal's IP addresses protects against requests from other parties. Configure your alert webhook server to only accept inbound connections from our IP addresses. Portal always makes requests from the IP addresses 35.203.150.117, 104.155.171.139 or 35.185.20.23.

Example Implementation

We provide a reference implementation of alert webhooks using TypeScript and Express. This example demonstrates best practices for handling alert webhook events, including:

• 🔒 IP address verification

• 🔑 Webhook secret validation

• ⚡ Async event processing

You can use this as a starting point for your own implementation:

git clone https://github.com/portal-hq/portal-alert-webhooks-example
cd portal-alert-webhooks-example
npm install

FAQ

What if I miss an alert webhook event?

• If your alert webhook is down or is not responding with 2xx status codes, Portal will retry sending the alert webhook event in intervals.

• If your alert webhook fails to receive the event:

  • You can find all of your alert webhooks using this endpoint.

  • You can then find an alert webhook's associated events using this endpoint.

  • You can replay the exact alert webhook event that failed to be delivered using this endpoint.

Should I process webhook events before responding?

No. Please acknowledge webhooks as quickly as possible. If you need to process the alert webhook event you receive, process it after responding to Portal with a 2xx status code. (We only wait up to 10 seconds to receive a response before considering the alert webhook event's delivery as failed.)

Support

And that's it! 🎉 You've now implemented alert webhooks and are receiving realtime wallet notifications for your Portal clients! As always, please reach out to our team if you have any questions.