Notify API FAQ

Frequently asked questions about the Notify API

What does the capacity limit error mean?

The capacity limit error means you've exceeded your total monthly compute units. To upgrade your capacity limits go to your Alchemy dashboard. Below is an example capacity limit error.

{
  "webhookId": "wh_127lzhz0dfwwimwe",
  "id": "whevt_55i2al4sc2ivp1m8",
  "createdAt": "2022-12-05T23:43:16.379Z",
  "type": "ADDRESS_ACTIVITY",
  "event": {
    "error": "Monthly capacity limit exceeded. Visit https://dashboard.alchemy.com/settings/billing to upgrade your scaling policy for continued service."
  }
}

What is the x-alchemy-signature?

The x-alchemy-signature is an Alchemy authentication token used to verify the source of your webhook requests and responses. The x-alchemy-signature ensures you’re getting responses from Alchemy and no other malicious source.

Where do I find my Alchemy auth token?

Find your Alchemy auth token in the upper-right corner of your Notify dashboard by clicking the AUTH TOKEN button.

1600 — Alchemy dashboard showing where to copy the Auth Token for the Notify API.

How many webhooks can I create?

As many as you like on Alchemy.

How many addresses can you add to a single webhook?

No more than 50,000 addresses per single webhook.

What's the difference between Notify V1 and V2?

The changes in webhook V2 are mostly formatting and parameter name updates. The primary changes are how you process response payloads.

To learn more about why we made this change, check out the blog post here. Although V1 webhooks are still be supported on Alchemy, all net-new webhooks created after Wednesday, April 27, 2022 will be V2.

V1 to V2 changes

V1 field	V2 change
`app`	Renamed to `appId` and is nested under the `event` field. No longer included for Address Activity webhooks.
`webhookType`	Renamed to `type`.
`network`	Nested under the `event` field.
`webhook_id`	Changed from an `int` to a `string`.
`timestamp`	Renamed to `createdAt`.
`fullTransaction`	Renamed to `transaction`. Now under the `event` field.
`null`	Fields are omitted from the response payload to improve latency & lower bandwidth use.

Retry logic is enabled for all V2 webhooks.

Why am I missing transactions in the response?

Double check that you're parsing the response payload correctly. Remember, transactions are returned in a list. Transactions that are mined within the same block will be returned within the same activity list.

Why are address activity events for the same transaction split across multiple response?

You many notice activity entries from the same transaction being split across multiple requests when using the Address Activity webhooks. This is expected behavior because webhook streams are currently separated by block and type. This means that if there are external, internal and token transfers all within the same transaction that occurred in block 49, you will still receive 3 separate webhook payloads, one for each of them.

What are some best practices when using webhooks with a large number of addresses?

When working with large address lists, we suggest that users assign no more than 50,000 addresses to each webhook. If you find yourself using many addresses, spin up a new webhook to ensure that you have a reliable and scalable system.

How are reorgs handled?

When a chain reorganization occurs, block logs on the old chain will be emitted again with the property removed set to true.

Why am I getting 5xx errors repeatedly setting up a webhook?

You may be seeing repeated 5xx errors because of automatic webhook-retry-logic where requests are retried for non-200 response codes and upon failures to reach your server.

One common mistake we see is users not responding with 2xx status codes on a successful response which will trigger a retry. To resolve, set-up a webhook listener.

How does reaching my CU limit impact my webhook's activity?

If you hit your CU limit and don't have autoscaling activated, all your active webhooks will be set to the 'paused' state. This means they'll temporarily stop operating until you manually unpause them or acquire more CUs.

What happens when my webhooks are in a 'paused' state?

When your webhooks are 'paused', they won't operate or trigger any notifications. You'll need to either wait for more CUs or upgrade to unpause them.

Why won't my paused webhooks automatically unpause after I upgrade or when I acquire more CUs?

We've noticed that many of our users use up all their CUs quickly at the month's start. To ensure these webhooks don't consume resources without proving their value, we ask that you manually unpause them, even after an upgrade.

Where can I find the app id?

Follow these steps to get your app id:

Go to your Alchemy dashboard and select the app for which you want to obtain the ID.
Click on the options button in top-right then "App Details"
Copy your app ID from the overlay