OpenAPI spec
Check out our OpenAPI spec for the full webhook message schema and more details on the data structure. You can use this to generate types for your language and easily parse the webhook message.Read action webhooks
For read actions, Ampersand attaches results to a webhook message in two ways:- Inline: In most cases, the result is directly included in the webhook’s
result
field. If a read action returns a large number of records, you might receive multiple webhooks in quick succession, each delivering a subset of the data. Read more about message frequency here. - URL: If a single record in the result set is over 300KB, it becomes too big to be sent over a webhook. In this case, the result won’t be included inline. Instead, the webhook message will contain a signed download URL in
resultInfo.downloadUrl
. The URL expires after 15 minutes.
resultInfo.type
indicates how the result is attached to the message:
If type is inline
, the full result is in the result
field.
If type is url
, you can fetch the full result by making a GET request to resultInfo.downloadUrl
.
In both cases, resultInfo.numRecords
tells you how many records are available in the result.
Example webhook message (inline)
Here’s a sample webhook message for a Salesforce Contact object:JavaScript
Example webhook message (URL)
JavaScript
Subscribe action webhooks
Subscribe action webhooks look very similar to read action webhooks with a few additional fields in each result entry:- subscribeEventType: this is the normalized event type string, which can be:
create
,update
,delete
,associationUpdate
(for HubSpot only). - subscribeEventType: this the raw event type string from the API provider.
- rawEvent: when available, this is the raw webhook event from the API provider.
JavaScript
Handling webhook results
Here’s some pseudo-code to illustrate how you can get parse result from a webhook:go
Handling the payload size
The maximum size of a webhook payload Ampersand may send to your destination is 300 KB. Most API gateways can handle this by default. If you implement your webhook using AWS Lambda or Google Cloud Run Functions, they will also be able to handle this payload size without any additional configuration. If you are using the Node.js framework Express in your webhook receiver, and are using the json middleware to parse request bodies, you will need to modify it to increase the maximum request body size.Handling the message frequency
By default, Ampersand will send you at most 1000 webhook messages per second across all your destinations. If you wish the change this limit, please contactsupport@withampersand.com
. Alternatively, you can set the delivery mode to on request to only get webhook messages when you request for them via an API call.
Webhook signature verification
Every webhook message that Ampersand sends includes a cryptographic signature. This signature lets you confirm that the payload is both authentic and unchanged when it reaches your system. Ampersand uses Svix to deliver webhooks to your destination, which is why the signature is sent in thesvix-signature
header. Each destination has its own unique secret, called the “webhook signing secret”, which is used to generate the signature.
To verify a webhook, you will need to:
- Get the signing secret for your destination from the Ampersand dashboard.
- Use that secret with any of the Svix libraries to verify the
svix-signature
header and confirm the message is valid. You can find more information on how to do this here.
Viewing your secret
To find a destination’s webhook signing secret, navigate to the destination in the Ampersand dashboard and click on “Click here to view the secret”.- Log in to the Ampersand dashboard & navigate to Destinations.
- Click on the destination you want to view the secret for.
- Click on “Click here to view the secret”.

Rotating your secret
If you need to rotate your signing secret for security reasons, you can do so from the Ampersand dashboard.- Navigate to the Destinations section in the Ampersand dashboard & click on the destination you want to rotate the secret for.
- Click on “Click here to view the secret”.
- Click on “Rotate secret” to rotate the secret & confirm the rotation.