Add contributing to app store doc - V2 (#2118)
* Add contributing to app store docs * Edit file structure diagram and fix build * Add doc to meta * Wrap example variabels in code block Co-authored-by: Peer Richelsen <peeroke@gmail.com>
This commit is contained in:
Joe Au-Yeung
GitHub
parent
53b202790e
commit
47c2fc3d89
3 changed files with 62 additions and 12 deletions
45
apps/docs/pages/developer/app-store.mdx
Normal file
45
apps/docs/pages/developer/app-store.mdx
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
title: Contributing to App Store
|
||||
---
|
||||
|
||||
# Contributing to the App Store
|
||||
|
||||
Since Cal.com is open source we encourage developers to create new apps for others to use. This guide is to help you get started.
|
||||
|
||||
## Structure
|
||||
|
||||
All apps can be found under `packages/app-store`. In this folder is `_example` which shows the general structure of an app.
|
||||
|
||||
```sh
|
||||
├──_example
|
||||
| ├──index.ts
|
||||
| ├──package.json
|
||||
| ├──.env.example
|
||||
|
|
||||
| ├──api
|
||||
| | ├──example.ts
|
||||
| | ├──index.ts
|
||||
|
|
||||
| ├──lib
|
||||
| | ├──adaptor.ts
|
||||
| | ├──index.ts
|
||||
|
|
||||
| ├──static
|
||||
| | ├──icon.svg
|
||||
```
|
||||
|
||||
## Getting Started
|
||||
|
||||
In the `package.json` name your package appropriately and list the dependencies needed for the package.
|
||||
|
||||
Next in the `.env.example` specify the environmental variables (ex. auth token, API secrets) that your app will need. In a comment add a link to instructions on how to obtain the credentials. Create a `.env` with your the filled in environmental variables.
|
||||
|
||||
In `index.js` fill out the meta data that will be rendered on the app page. Under `packages/app-store/index.ts`, import your app and add it under `appStore`. Your app should now appear in the app store.
|
||||
|
||||
Under the `/api` folder, this is where any API calls that are associated with your app will be handled. Since cal.com uses Next.js we use dynamic API routes. In this example if we want to hit `/api/example.ts` the route would be `{BASE_URL}/api/integrations/_example/example`. Export your endpoints in an `index.ts` file under `/api` folder and import them in your main `index.ts` file.
|
||||
|
||||
The `/lib` folder is where the functions of your app live. For example, when creating a booking with a MS Teams link the function to make the call to grab the link lives in the `/lib` folder. Export your endpoints in an `index.ts` file under `/lib` folder and import them in your main `index.ts` file.
|
||||
|
||||
The `/static` folder is where your assets live.
|
||||
|
||||
If you need any help feel free to join us on [Slack](https://cal.com/slack)
|
||||
|
|
@ -4,5 +4,6 @@
|
|||
"code-styling": "Code styling",
|
||||
"project-structure": "Project structure",
|
||||
"pull-requests": "Pull requests",
|
||||
"adding-css": "Adding CSS"
|
||||
"adding-css": "Adding CSS",
|
||||
"app-store": "Contributing to App Store"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@ title: Webhooks
|
|||
---
|
||||
|
||||
# Webhooks
|
||||
|
||||
## Create a new Webhook
|
||||
|
||||
1. Go to [Your Integrations](https://app.cal.com/integrations).
|
||||
|
|
@ -23,22 +24,27 @@ title: Webhooks
|
|||
3. Press the button and from here your webhook will no longer work and be deleted.
|
||||
|
||||
## Webhook metadata
|
||||
|
||||
Metadata is a way to pass extra information to Cal.com about a booking that is returned through a webhook.
|
||||
|
||||
### Example
|
||||
|
||||
The best way to explain this is with an example. Let's say you're a bank, and people register an account on your website, but you want them to book an onboarding call with your team to get set up. You could send them to your Cal.com booking link as part of your onboarding process, but when the webhook is returned, it may be difficult to match up which user booked a meeting with the user's account in your own database. Hence, you can pass a `user_id` value for instance as a URL parameter, which makes no difference to the booking process, but when the webhook is returned, you will receive the metadata as part of the webhook payload.
|
||||
|
||||
Metadata is passed as a URL parameter on top of your booking link and follows the following syntax:
|
||||
|
||||
```text
|
||||
metadata[key_name]=value
|
||||
```
|
||||
|
||||
For example, if your booking link is `cal.com/rick/quick-chat`, you can pass a user ID of 123 like so:
|
||||
|
||||
```text
|
||||
cal.com/rick/quick-chat?metadata[user_id]=123
|
||||
```
|
||||
|
||||
As a result, the webhook will be returned in this format:
|
||||
|
||||
```text
|
||||
{ <other event details>, metadata: { user_id: 123 } }
|
||||
```
|
||||
|
|
@ -47,10 +53,10 @@ As a result, the webhook will be returned in this format:
|
|||
|
||||
Customizable webhooks are a great way reduce the development effort and in many cases remove the need for a developer to build an additional integration service. Using a custom template you can easily decide what data you receive in your webhook endpoint, manage the payload and setup related workflows accordingly. Here’s a breakdown of the payload that you would receive via an incoming webhook.
|
||||
|
||||
### Webhook structure
|
||||
### Webhook structure
|
||||
|
||||
| Variable | Type | Description |
|
||||
|---------------------|----------|----------------------------------------------------------------------------------------|
|
||||
| ------------------- | -------- | -------------------------------------------------------------------------------------- |
|
||||
| triggerEvent | String | The name of the trigger event [BOOKING_CREATED, BOOKING_RESHEDULED, BOOKING_CANCELLED] |
|
||||
| createdAt | String | The time of the webhook trigger |
|
||||
| type | String | The event-type slug |
|
||||
|
|
@ -68,10 +74,10 @@ Customizable webhooks are a great way reduce the development effort and in many
|
|||
| team?.name | String | Name of the team booked |
|
||||
| team?.members | String[] | Members of the team booked |
|
||||
|
||||
### Person structure
|
||||
### Person structure
|
||||
|
||||
| Variable | Type | Description |
|
||||
|-----------------|--------|-----------------------------------------------------------------------|
|
||||
| --------------- | ------ | --------------------------------------------------------------------- |
|
||||
| name | String | Name of the individual |
|
||||
| email | String | Email of the individual |
|
||||
| timeZone | String | Timezone of the individual ("America/New_York", "Asia/Kolkata", etc.) |
|
||||
|
|
@ -79,16 +85,14 @@ Customizable webhooks are a great way reduce the development effort and in many
|
|||
|
||||
### Example usage of variables for custom template:
|
||||
|
||||
```sh
|
||||
{
|
||||
|
||||
|
||||
"content": "A new event has been scheduled",
|
||||
"type": "{{type}}",
|
||||
"type": "{{type}}",
|
||||
"name": "{{title}}",
|
||||
"organizer": "{{organizer.name}}",
|
||||
"booker": "{{attendees.0.name}}"
|
||||
|
||||
}
|
||||
|
||||
|
||||
|
||||
|
||||
}
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue