Webhooks

• Create a new issue in your bug tracking software when a customer reports a bug
• Deploy a new version of your application when your CI pipeline finishes building code

TypeScriptPythonYAMLStudio

typescript
Copied
1
// my_task.airplane.ts
2
export default airplane.task(
3
  {
4
    slug: "my_task",
5
    webhooks: { my_webhook: { requireAirplaneToken: false } },
6
    // Shorthand with no configuration:
7
    // webhooks: ["my_webhook"]
8
  },
9
  async () => {...}
10
);

python
Copied
1
# my_task_airplane.py
2
@airplane.task(
3
    webhooks=[
4
        airplane.Webhook(
5
            slug="my_webhook",
6
            require_airplane_token=False,
7
        ),
8
    ],
9
)
10
def my_task(webhook_payload: airplane.JSON):
11
    pass

In your task definition file (the file with extension .task.yaml), declare a slug for each webhook. For example, a SQL task with a webhook would look like this:

yaml
Copied
1
# update_customer.task.yaml
2
slug: update_customer
3
name: update customer
4
sql:
5
  resource: demo_db
6
  entrypoint: update_customer.sql
7
  queryArgs:
8
    customer_id: "{{params.webhook_payload.customer.id}}"
9
webhooks:
10
  my_webhook:
11
    requireAirplaneToken: false
12
  # Shorthand with no configuration:
13
  # - my_webhook

You can create a new webhook in the Advanced section of the task editor:

typescript
Copied
1
// my_task.airplane.ts
2
export default airplane.task(
3
  {
4
    slug: "my_task",
5
    webhooks: { my_webhook: { requireAirplaneToken: false } },
6
  },
7
  async (params) => {
8
    const { body } = params.webhook_payload;
9
    // Do something with the body.
10
  }
11
);

python
Copied
1
# my_task_airplane.py
2
@airplane.task(
3
    webhooks=[
4
        airplane.Webhook(
5
            slug="my_webhook",
6
            require_airplane_token=False,
7
        ),
8
    ],
9
)
10
def my_task(webhook_payload: airplane.JSON):
11
    body = webhook_payload["body"]
12
    # Do something with the body.

yaml
Copied
1
# update_customer.task.yaml
2
slug: update_customer
3
name: update customer
4
sql:
5
  resource: demo_db
6
  entrypoint: update_customer.sql
7
  queryArgs:
8
    customer_id: "{{params.webhook_payload.customer.id}}"
9
webhooks:
10
  my_webhook:
11
    requireAirplaneToken: false

bash
Copied
1
curl https://api.airplane.dev/v0/webhooks/prod/tsk20230616zclw0nuh37q/my_webhook_secret \
2
  -H "Content-Type: application/json" \
3
  -d '{
4
    "cats": { "name": "Mittens", "age": 5 }
5
  }'

JSON
Copied
1
{
2
  "slug": "my_webhook",
3
  "headers": {
4
    "Content-Type": "application/json"
5
  },
6
  "body": {
7
    "cats": { "name": "Mittens", "age": 5 }
8
  },
9
  "rawBody": "eyJjYXRzIjogeyJuYW1lIjogIk1pdHRlbnMiLCAiYWdlIjogNX19"
10
}

typescript
Copied
1
// stripe_webhook.airplane.ts
2
import airplane from "airplane";
3
import { Stripe } from "stripe";
4

5
export default airplane.task(
6
  {
7
    slug: "stripe_events",
8
    name: "Stripe events handler",
9
    envVars: {
10
      STRIPE_API_KEY: {
11
        config: "stripe_api_key",
12
      },
13
      STRIPE_WEBHOOK_SECRET: {
14
        config: "stripe_webhook_secret",
15
      },
16
    },
17
    webhooks: ["stripe_prod"],
18
    // Webhooks adds a webhook_payload parameter for your task
19
  },
20
  async (params) => {
21
    // Retrieve the Stripe API key and webhook secret from your environment variables
22
    const apiKey = process.env.STRIPE_API_KEY;
23
    const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
24

25
    // Create a new instance of the Stripe SDK using your API key.
26
    const stripe = new Stripe(apiKey, { apiVersion: "2022-11-15" });
27

28
    // Verify the webhook signature using the raw body.
29
    // Retrieve the Stripe webhook signature from the headers
30
    const { rawBody, headers } = params.webhook_payload;
31
    const decodedBody = Buffer.from(rawBody, "base64").toString("utf-8");
32
    const stripeSignature = headers["Stripe-Signature"];
33
    try {
34
      const event = stripe.webhooks.constructEvent(decodedBody, stripeSignature, webhookSecret);
35
      // At this point, the webhook signature is valid
36
      // You can now handle the event based on its type
37
      switch (event.type) {
38
        case "payment_intent.created":
39
          // Handle payment intent created event
40
          break;
41
        // Add more cases for other event types as needed
42
        default:
43
          // Handle unrecognized event types
44
          break;
45
      }
46
      return { body: "Webhook signature verified successfully" };
47
    } catch (err) {
48
      // An error occurred during signature verification
49
      throw new Error("Webhook signature verification failed: " + err);
50
    }
51
  },
52
);

typescript
Copied
1
import airplane from "airplane";
2
import crypto from "node:crypto";
3

4
export default airplane.task(
5
  {
6
    slug: "linear_events",
7
    name: "Linear events handler",
8
    envVars: {
9
      // Create a webhook in the Linear UI: https://linear.app/settings/api
10
      LINEAR_WEBHOOK_SECRET: {
11
        config: "linear_webhook_secret",
12
      },
13
    },
14
    webhooks: ["linear_issues"],
15
  },
16
  async (params) => {
17
    // Retrieve the webhook secret from an environment variable.
18
    const webhookSecret = process.env.LINEAR_WEBHOOK_SECRET;
19
    if (!webhookSecret) {
20
      throw new Error("Missing LINEAR_WEBHOOK_SECRET");
21
    }
22

23
    const {
24
      webhook_payload,
25
    }: {
26
      webhook_payload: {
27
        body: Record<string, any>;
28
        headers: Record<string, any>;
29
        rawBody: string;
30
      };
31
    } = params as any;
32

33
    // Verify the webhook signature using the raw body.
34
    const decodedBody = Buffer.from(webhook_payload.rawBody, "base64").toString("utf-8");
35
    const signature = crypto.createHmac("sha256", webhookSecret).update(decodedBody).digest("hex");
36
    if (signature !== webhook_payload.headers["Linear-Signature"]) {
37
      throw new Error("Invalid signature");
38
    }
39

40
    // At this point, the webhook signature is valid.
41
    // You can now handle the event based on its type.
42
    switch (webhook_payload.body.type) {
43
      case "Issue":
44
        // Handle changes to Linear issues
45
        break;
46
    }
47

48
    return params;
49
  },
50
);