Skip to content

Webhooks

Webhooks allow you to receive real-time notifications when specific events occur in your app. When an event is triggered, Capawesome Cloud sends an HTTP POST request to your configured endpoint, enabling integrations with external services like CI/CD pipelines, Slack, or custom backends.

Events

The following events are currently supported:

Event Description
app_build_created Triggered when a new app build is created.
app_deployment_created Triggered when a new deployment is created.
job_created Triggered when a new job is created.
job_finished Triggered when a job finishes.

Need an event that's not listed here? Let us know and we'll look into adding it.

Payload

Each webhook request contains a JSON body with an event field indicating the event type and a data field containing the event payload. Here is an example of a job_finished event:

{
  "event": "job_finished",
  "data": {
    "id": "16555c02-a320-4bec-a14a-52754d783970",
    "appBuildId": "647d1fe4-9cb7-4f25-afaf-7a0c13a1bb8c",
    "appDeploymentId": null,
    "appId": "70922e93-0944-48cc-a560-61135ab291ad",
    "canceledAt": 1771143284003,
    "canceledBy": "f624e455-b19c-4f17-8282-e4a7a02597f3",
    "finishedAt": 1771143284003,
    "inProgressAt": 1771143275311,
    "inProgressTimeInSeconds": 8,
    "organizationId": "a7249949-a705-4952-a293-a06df84950dc",
    "pendingAt": 1771143256381,
    "pendingTimeInSeconds": 18,
    "queuedAt": null,
    "queueTimeInSeconds": null,
    "stack": "macos-tahoe",
    "status": "canceled",
    "totalTimeInSeconds": 27,
    "createdAt": 1771143256161,
    "createdBy": "f624e455-b19c-4f17-8282-e4a7a02597f3"
  }
}

Managing Webhooks

Webhooks are configured per app. To manage webhooks, navigate to Settings > Webhooks in your app's sidebar in the Capawesome Cloud Console. From there, you can create, edit, and delete webhooks.

Each webhook has the following properties:

  • Name (required): A human-readable name to identify the webhook.
  • URL (required): The endpoint URL that receives the HTTP POST requests.
  • Events (required): One or more events that trigger the webhook.
  • Signing Secret (optional): A secret used to sign each request via the X-Signature header so the receiver can verify the payload authenticity.
Testing

You can use webhook.cool to generate a temporary URL for testing your webhook configuration.

Verifying Signatures

If a signing secret is configured, each webhook request includes an X-Signature header containing an HMAC-SHA256 signature of the request body. You should verify this signature to ensure the request is authentic and has not been tampered with.

The following example shows how to verify the signature in Node.js:

import crypto from "node:crypto";

const secret = "SIGNING_SECRET";
const hmac = crypto.createHmac("sha256", secret);
const digest = Buffer.from(
  hmac.update(request.rawBody).digest("hex"),
  "utf8"
);
const signature = Buffer.from(request.get("X-Signature") || "", "utf8");

if (!crypto.timingSafeEqual(digest, signature)) {
  throw new Error("Invalid signature.");
}

Delivery History

Every webhook keeps a delivery log. Each delivery record includes:

  • Event: The event that triggered the delivery.
  • Request Body: The JSON payload sent to the endpoint.
  • Response Status Code: The HTTP status code returned by the endpoint.
  • Response Body: The response body returned by the endpoint.
  • Sent At: The timestamp of the delivery attempt.

Deliveries with a 2xx status code are marked as successful. Failed deliveries can be manually resent from the Capawesome Cloud Console.