Skip to main content

Webhook Notifications

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

Takumi API can send webhook notifications when a workflow (such as an assessment) completes. This lets you detect workflow completion without polling and automatically start retrieving results or running follow-up processes.

Workflow Completion Event​

When a workflow finishes, an HTTP POST request is sent to the specified webhook endpoint. The event type is api.workflow_run.exited.

{
  "type": "api.workflow_run.exited",
  "timestamp": "2000-01-01T00:00:00Z",
  "data": {
    "workflow_id": "whitebox-assessment",
    "workflow_run_id": "TWR..."
  }
}

Use data.workflow_run_id to identify the workflow run and retrieve its results from the /o/{org_id}/workflows/{workflow_id}/describe endpoint.

Specifying Webhook Endpoints​

In the workflow dispatch request body (/o/{org_id}/workflows/{workflow_id}/dispatch), specify one or more endpoint IDs in notification.webhook_endpoint_ids to receive a notification when that workflow completes.

{
  "input": { /* ... */ },
  "notification": {
    "webhook_endpoint_ids": ["WH..."]
  }
}

Webhook Specifications​

When an event occurs, an HTTP POST request is sent to the specified webhook endpoint.

The request body has the following structure:

{
  "type": "{event_type}",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {/* event-specific data */}
}

The webhook endpoint must return an HTTP 2xx status code within 10 seconds to acknowledge successful receipt. Responses with 3xx status codes are treated as failures; redirects are not followed.

If the request fails (non-2xx response, timeout, or network error), the service automatically retries delivery.

Webhook delivery is at-least-once, meaning the same event may be delivered more than once. Each request includes a webhook-id header; requests with the same webhook-id are redeliveries of the same event. We recommend implementing your endpoint idempotently using the webhook-id.

Verifying Signatures​

Always verify the signature of incoming requests to confirm they were sent by this service. The service uses a signing scheme compliant with the Standard Webhooks specification.

Here is an example implementation in TypeScript:

import { Webhook } from "standardwebhooks";

const wh = new Webhook(signingSecret);

// Verify the signature using the request headers and body
wh.verify(requestBody, {
  "webhook-id": req.headers.get("webhook-id"),
  "webhook-timestamp": req.headers.get("webhook-timestamp"),
  "webhook-signature": req.headers.get("webhook-signature"),
});

const payload = JSON.parse(requestBody);

Setting Up Webhook Endpoints​

Register a Webhook Endpoint​

Go to Settings > Webhook Endpoints and click "Register a new webhook endpoint" to enter the destination URL and a description.

Once registered, the endpoint ID (WH... format) and signing secret are displayed.

warning

The signing secret is only shown on this screen. Be sure to copy and store it securely before closing this page. If you lose it, you can reissue one via "Rotate signing secret."

Send a Test Message​

Once your receiving server is running, verify that webhooks are delivered correctly before running a workflow. In Settings > Webhook Endpoints, click the ... menu on the endpoint row and select "Send test message" to send a test payload.

If your server receives the request and returns HTTP 2xx, you're all set.

Rotating the Signing Secret​

To regenerate the secret, click the ... menu on the endpoint row and select "Rotate signing secret".

For 24 hours after rotation, the service signs webhook requests with both the old and new secrets, including multiple signatures in the request per the Standard Webhooks specification. This means both servers using the old secret and servers using the new secret will accept webhook notifications from the service during this period. As long as you update your receiving server's configuration within 24 hours, you can rotate the secret without any interruption in webhook delivery.

Here is an example procedure:

  1. Perform the rotation and obtain the new signing secret
  2. Update the environment variables or configuration files on your receiving server with the new secret and restart the server
  3. Verify with a test message
  4. (After 24 hours, webhook requests will only be signed with the new secret)
Last updated on