Skip to main content

Webhook Guide

Looking for the events themselves?

For the events a webhook can receive, what each one contains, and when it is sent, see Webhooks. This guide covers creating, viewing, updating, and deleting a webhook in the Console or with the API.

A webhook sends events from Mapped to an endpoint you run, as they happen, so you don't have to poll the API for changes. You choose which events it receives with a filter: for example the results of a live query, changes to a connector's entities, or vulnerability (CVE) findings on your devices. Webhooks lists every event type.

Webhooks can be created in two different ways - either using the UI or through the API. We'll walk through the steps on the UI first, and then move into the API calls you can use.

Working with the Webhooks UI​

Creating a Webhook​

Once you're on the Webhooks page in Tools, you'll initially see a list of the webhooks that already exist. If this is your first time, it'll be a mostly blank page. Up at the top right is a Create Webhook button; clicking that will bring you to the page with the various fields you will need to fill out.

Field NameDescription
NameDescriptive name of the webhook, and should include some indicator of the data being sent
Max Retry CountHow many times Mapped sends an event again when your endpoint does not accept it, before dropping it; see Responding and Retries
MethodChoose POST: events are delivered as HTTP POST requests
URLThe destination for the events, like https://www.example.com/mapped_payload. HTTP and HTTPS URLs are accepted; use HTTPS
Auth TypeHow Mapped authenticates to your endpoint: no auth, Basic, an API key header, or OAuth 2.0 client credentials; see Authentication
Filter TypeThe JSON Expression (a JSONPath filter) that selects which events the webhook receives

Each event published in your org is tested against the filter; events from other orgs never reach your webhooks. Most filters match the event's type, its source, or both. For example, to receive the results of one live query, match its source:

@.source == '//com.mapped/orgs/ORG8Si1dkzGEYZgxrR4ZYAbCD/liveQueries/LVQAERav1iu5vkp6Qhkmf1234'

The ID listed after orgs is your org ID (if you're not sure what that is, you can make a call to organization), and the ID after liveQueries is the ID of the Live Query - view the Live Query docs for how to create one and get its ID.

To receive every change to your connectors' entities, match the event type instead:

@.type == 'connectorEntitiesChangelog'

Note the single quotes around each value; without them, the filter won't match. Filtering Events lists the fields and operators you can use, with more examples, and each event type's page shows the filter for it.

Once all the fields are populated, hit the Save button at the bottom right. The webhook starts receiving events within about a minute.

Editing a Webhook​

To edit a webhook in the UI, just click on one from the list, make the needed changes, and hit the Save button at the bottom right.

Deleting a Webhook​

Similarly, to delete a webhook in the UI, select one from the list and then hit the Delete button at the bottom left. You'll be prompted to confirm you really want to delete it; if you click Delete, the webhook will be removed forever.

Creating Webhooks Through the API​

Creating a webhook through the API doesn't require making multiple calls - everything is contained within createWebhookTarget. If you drill down into the API Reference a little further, you'll get to WebhookTarget, where the majority of the important fields are located. The critical ones are:

Field NameDescription
contentModeHow the event is laid out in the request: binary (the default, where the body is the event's data) or STRUCTURED (the whole event as JSON); see Content Modes
enabledDetermines whether the webhook is enabled or not - set it to true or false. Disabled webhooks still exist, but won't send any data to your endpoint
eventFiltersThe JSON Expression that selects which events the webhook receives (see the previous section, and Filtering Events)
eventExtensionsCustom key:value pairs added to every event the webhook sends, for routing or other purposes in your endpoint; supported values are boolean, string and integer (see Custom Extensions)
httpTargetThe endpoint details: targetUri (an HTTP or HTTPS URL; use HTTPS), the method (use POST: events are always delivered with POST), the auth (noAuth, basicAuth, apiKey, or oauth2ClientCredentialsFlow; see Authentication) and hmac256 (signing keys: Mapped signs every request with each key and never sends the keys themselves; see Verifying Webhook Signatures)
maxRetryHow many times to send an event again when your endpoint does not accept it, before dropping it; 10 when not set

The following example creates a webhook linked to a live query with:

  • the ID LVQAERav1iu5vkp6Qhkmf1234
  • inside the org with the ID ORG8Si1dkzGEYZgxrR4ZYAbCd
  • enabled set to true
  • a maxRetry value of 10
  • sending data to the endpoint https://example.com/d123456abcde
  • using a POST
  • with no auth included
mutation {
createWebhookTarget(
input: {
target: {
name: "Live Query Subscription"
eventFilters: {
jsonExpressionFilter: {
jsonPathExpression: "@.source == '//com.mapped/orgs/ORG8Si1dkzGEYZgxrR4ZYAbCD/liveQueries/LVQAERav1iu5vkp6Qhkmf1234'"
}
}
httpTarget: {
method: POST
targetUri: "https://example.com/d123456abcde"
auth: { noAuth: true }
}
maxRetry: 10
enabled: true
}
}
) {
target {
id
name
eventFilters {
jsonExpressionFilter {
jsonPathExpression
}
}
httpTarget {
auth {
noAuth
}
method
targetUri
}
maxRetry
enabled
}
}
}

View Existing Webhooks Through the API​

To view the webhooks you've created using the API, you would call webhookTargets. In our example, we'll pull the id, name, the httpTarget information (including the URL and auth) and the eventFilters (which will typically be the JSON Expression defined when the webhook was created):

{
webhookTargets {
id
name
httpTarget {
targetUri
method
auth {
noAuth
}
}
eventFilters {
jsonExpressionFilter {
jsonPathExpression
}
}
}
}

Updating Webhooks Through the API​

If you wanted to edit a webhook - change the URL, disable or enable it, change the payload's content mode - you would call updateWebhookTarget.

In this example, we'll update the contentMode field; you will also need to include the id field in an updateWebhookTarget call:

mutation {
updateWebhookTarget(
input: {target: {id: "WHSUB5nS9Ng7P2NCWZgT551aiCG", contentMode: {value: STRUCTURED}}}
) {
target {
id
name
contentMode
}
}
}

Deleting Webhooks Through the API​

To delete a webhook, call deleteWebhookTarget and just pass the ID of the webhook you want removed.

mutation {
deleteWebhookTarget(input: { id: "WHSUBMgoLD3fHY329pKANvdAb12" }) {
_
}
}

Webhook Payload Examples​

What a webhook receives depends on the event; Webhooks describes every event type, its payload, and when it is sent.

For example, a webhook subscribed to a live query receives an event whenever the query's result changes, such as when a new site is added to your org. The payload is the full current result, with the live query ID for correlation if you have more than one live query sending to the same endpoint:

{
"lastResult":{
"sites":[
{
"id":"SITEA2yCZ58ZpJsE7hH3Sj52CP",
"name":"OG Site"
},
{
"id":"SITETeZNmbxTZKbN6ArdANbyvX",
"name":"New Site"
}
]
},
"liveQueryId":"LVQCJcMTCrz86gs8UteKroy34"
}

With contentMode unset (binary), that payload is the request body, and the event's other attributes (its id, type, source, time, and so on) arrive as ce- headers. If you set the contentMode to STRUCTURED, the body is the whole event, including any eventExtensions you set on the webhook (the values like myint, mystring and mybool below):

{
"specversion":"1.0",
"id":"LVQCH8x2c4Yq3cGmbFUqcm5H9Ad",
"source":"//com.mapped/orgs/ORG8Si1dkzGEYZgxrR4ZYAbCD/liveQueries/LVQCJcMTCrz86gs8UteKroy34",
"type":"mapped.livequery.resultChangeNotification.v1.created",
"datacontenttype":"application/json",
"time":"2026-11-19T17:02:03.512Z",
"data":{
"lastResult":{
"sites":[
{
"id":"SITEA2yCZ58ZpJsE7hH3Sj52CP",
"name":"OG Site"
},
{
"id":"SITETeZNmbxTZKbN6ArdANbyvX",
"name":"New Site"
}
]
},
"liveQueryId":"LVQCJcMTCrz86gs8UteKroy34"
},
"orgid":"ORG8Si1dkzGEYZgxrR4ZYAbCD",
"myint":1234,
"mystring":"hello world",
"mybool":true
}

Receiving Events describes the request in full, including retries, duplicates, and ordering.

Verifying Webhook Signatures​

When a webhook has signing keys (httpTarget.hmac256.signingKeys), Mapped signs every request it sends with each key and adds:

HeaderValue
X-Authorization-DigestHMACSHA256
X-Mapped-Signature-0The signature made with the first signing key.
X-Mapped-Signature-1, …One more header for each further key, numbered from 0 in the order of signingKeys.

Each signature is the HMAC-SHA256 of the raw request body, keyed with the signing key and base64-encoded. The keys themselves are never sent. Accept a request when any signature you compute matches any X-Mapped-Signature-<n> header; otherwise reject it. If no signing key is configured, requests are sent unsigned.

Verifying Signatures has verification code in TypeScript, Python, and Go, and how to rotate a key without downtime.