Skip to main content

Webhooks Overview

A webhook pushes events from Mapped to an HTTPS endpoint you run, as they happen, so you don't have to poll the API for changes. Each event is a CloudEvent with a type that says what happened, a source that says what it happened to, and a JSON data payload with the details.

This section covers the events Mapped sends, what each one contains and when it is sent, and how to receive them reliably. To create, edit, or delete a webhook, use the Webhooks page in the Console or the API calls in the Webhook Guide.

How It Works​

  1. Something changes in your org: a live query's result changes, a connector's entities are applied to the graph, a vulnerability is found on a device, and so on.
  2. Mapped publishes an event for it. Events only ever go to webhooks in the org they belong to.
  3. Each webhook in that org has a filter. When the filter matches the event, Mapped sends the event to the webhook's endpoint with an HTTP POST. When no webhook matches, the event is not sent anywhere.

A webhook is therefore two things: where to send events (the endpoint URL, its authentication, and an optional signing key), and which events to send (the filter).

Event Types​

Event typeSent whenReference
mapped.livequery.resultChangeNotification.v1.createdA live query's result changesLive Query Events
connectorEntitiesChangelogA connector's entities are added to, updated in, or removed from the graphConnector Entity Events
mapped.security.cve.*A vulnerability scan finishes, or a CVE finding on a device, its disposition, or a comment changesVulnerability (CVE) Events
webhooks.subscriptions.created, webhooks.subscriptions.deletedA webhook is created or deleted in your orgWebhook Lifecycle Events

New event types are added over time. A webhook only receives the types its filter matches, so new types never reach an existing webhook unless its filter already matches them; filter on type (see Filtering Events) rather than sending everything to one endpoint.

Quick Start​

  1. Stand up an endpoint that accepts POST requests over HTTPS and answers 2xx quickly. See Receiving Events for what the request looks like.

  2. Pick the events you want from the table above and write a filter for them, for example:

    @.type == 'connectorEntitiesChangelog'
  3. Create the webhook in the Console, or with createWebhookTarget:

    mutation {
    createWebhookTarget(
    input: {
    target: {
    name: "Connector changes"
    eventFilters: { jsonExpressionFilter: { jsonPathExpression: "@.type == 'connectorEntitiesChangelog'" } }
    httpTarget: {
    method: POST
    targetUri: "https://example.com/mapped/events"
    auth: { noAuth: true }
    hmac256: { signingKeys: ["a-long-random-secret"] }
    }
    maxRetry: 10
    enabled: true
    }
    }
    ) {
    target { id name }
    }
    }
  4. Verify each request with your signing key, de-duplicate on the event id, and process the event. A new webhook can take up to a minute to start receiving events.

Good Practices​

  • Answer fast, work later. Return 2xx as soon as you have stored the request, and do the work in the background. A request that takes longer than 10 seconds counts as failed and is sent again.
  • Expect duplicates. Delivery is at least once. Use the event id to ignore an event you have already processed.
  • Don't rely on order. Events can arrive out of order, especially around retries. Use the event's time and the payload's own timestamps to decide which is newest.
  • Reconcile now and then. Webhooks tell you that something changed; the API is the source of truth. If your endpoint was down for longer than the retry window, or an event never arrived, query the API to catch up.
  • Verify signatures. Configure a signing key and reject requests whose signature does not match. See Verifying Signatures.