Webhooks

Webhooks push an HTTP POST to a URL you control whenever something happens to a report in your organization: created, updated, triaged, and so on. Use them to sync reports into your own tracker, notify a channel, or trigger automation. A channel’s transmit steps deliver through webhooks too; see the Channels API.

Set up in the app

In the app, open Webhooks and add one with:

• a name,
• the URL to deliver to, and
• the events you want to receive (checkboxes).

Note

Webhooks are part of the integrations feature set. If you don’t see the Webhooks page, the feature isn’t enabled for your organization yet.

Events

You can subscribe to any of these report events:

Event	Fires when
Report::Created	A report is created.
Report::Updated	A report is updated.
Report::Read	A report is read.
Report::Destroyed	A report is deleted.
Report::Inbox::Received	A report lands in the inbox.
Report::Inbox::Stored	An inbox report is stored.
Report::Processing::Closed	A report is closed.
Report::Processing::Reopened	A closed report is reopened.

Discover events via the API

Event types have stable ids you attach when subscribing. List them:

List subscribable events

curl https://api.disclosebot.io/v1/webhook_event_types \
  -H "Authorization: Bearer disclosebot_svc_xxxxxxxx" \
  -H "Accept: application/vnd.api+json"

Each item has a name (e.g. Events::Report::Created) and a short_name (Report::Created).

Manage via the API

Webhooks are a full CRUD resource (GET/POST/PATCH/DELETE /v1/webhooks). Subscribe by attaching a trigger_event_types relationship, referencing ids from the discovery endpoint:

Create a webhook subscribed to two events

curl -X POST https://api.disclosebot.io/v1/webhooks \
  -H "Authorization: Bearer disclosebot_svc_xxxxxxxx" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "webhook",
      "attributes": { "name": "My integration", "url": "https://example.com/hooks", "enabled": true },
      "relationships": {
        "trigger_event_types": {
          "data": [
            { "type": "trigger_event_type", "id": "<created-id>" },
            { "type": "trigger_event_type", "id": "<closed-id>" }
          ]
        }
      }
    }
  }'

See the Platform API reference for the full webhook and event-type schemas.

Delivery

When a subscribed event fires, we POST a JSON body to your URL. Every delivery is signed, has one shape, and is recorded so you can see what we sent and what you answered. That is covered on its own page: Webhook deliveries.

The one-time signing secret is in the response to creating the webhook, under data.attributes.signing_secret. Store it then; it cannot be read back.

Rotating the signing secret

If a secret is lost or exposed, open the webhook in the app and choose Rotate. The new secret is shown once, on that page, and cannot be read back afterwards either.

Rotation takes effect immediately and there is no overlap: the previous secret stops signing at once, so every consumer still verifying with it will reject deliveries until you give them the new one. Have somewhere to put it before you press the button.

A rotated secret does not re-sign anything already sent. Deliveries signed with the old secret keep the signature they were sent with, and only new ones use the new secret.