Wyzwalacze to zdarzenia, które uruchamiają integrację. Ten przewodnik opisuje API, którego Twoja aplikacja użyje do uruchamiania integracji.

Informacje ogólne

Bloki wyzwalaczy określają, kiedy uruchamia się integracja. Wiele aplikacji uruchamia wyzwalacze na podstawie webhooków z systemów zewnętrznych, ale możesz użyć dowolnego zdarzenia.

Twoja aplikacja musi obsługiwać trzy kroki:

1. Użytkownik dodaje Twój wyzwalacz do przepływu pracy: monday wywołuje Twój adres URL subskrypcji
2. Twoja aplikacja uruchamia subskrypcję: wywołujesz adres URL webhooka subskrypcji
3. Użytkownik usuwa Twój wyzwalacz: monday wywołuje Twój adres URL anulowania subskrypcji

Aby dowiedzieć się, jak skonfigurować blok w interfejsie monday, zacznij tutaj.

Dokumentacja

Adres URL subskrypcji

monday wyśle żądanie POST na adres URL subskrypcji, gdy użytkownik utworzy przepływ pracy z Twoim wyzwalaczem. Żądanie będzie zawierać adres URL webhooka. Gdy Twoja aplikacja wywoła ten adres, monday uruchomi kolejne akcje w integracji.

Metoda: POST

Treść żądania

{
  "payload": {
    "webhookUrl": "https://api-gw.monday.com/automations/apps-events/481709001",
    "subscriptionId": 481709001,
    "inboundFieldValues": {
      "number": 10,
      "string": "10"
    },
     "credentialsValues":   { 
       "credentials-key": { 
         userCredentialsId: 12345, 
         accessToken: "abcd1234" 
       } 
     },
    "inputFields": {
      "number": 10,
      "string": "10"
    },
    "recipeId": 629280,
    "integrationId": 398528596
  }
}

Nagłówek autoryzacji

Żądanie będzie zawierać token JWT autoryzacji w nagłówkach.

Adres URL webhooka

Ładunek zawiera adres URL webhooka, którego Twoja aplikacja może użyć do wywołania wyzwalacza. W następnej sekcji znajdziesz instrukcje, jak z niego skorzystać.

Odpowiedź

Twój endpoint powinien zwrócić status 200. Odpowiedź musi też zawierać nagłówek Content-Type:application/json.

Zapisz szczegóły subskrypcji w pamięci aplikacji, aby móc później ją uruchomić. Możesz przechowywać te dane w pamięci monday code i użyć identyfikatora subskrypcji jako klucza dostępu.

Twój endpoint powinien zwrócić webhookId. Ta wartość zostanie zwrócona podczas zdarzenia anulowania subskrypcji. Jeśli nie przekażesz identyfikatora webhooka, zostanie użyty subscriptionId.

import { Storage } from '@mondaycom/apps-sdk';

// Initialize storage instance
const storage = new Storage(token);

/**
 * Handles subscription requests and stores subscription data
 * @param {Object} req - Express request object
 * @param {Object} res - Express response object
 * @returns {Promise<Object>} Response with webhook ID
 */
export async function subscribe(req, res) {
  try {
    const { payload } = req.body;
    const {
      inputFields,
      webhookUrl,
      subscriptionId,
      recipeId,
      integrationId
    } = payload;

    const subscription = {
      inputFields,
      webhookUrl,
      recipeId,
      integrationId
    };

    await storage.set(subscriptionId, JSON.stringify(subscription));

    return res.status(200).send({ webhookId: subscriptionId });
  } catch (error) {
    console.error('Error in subscribe:', error);
    return res.status(500).send({ error: 'Failed to process subscription' });
  }
}

Uruchamianie bloku

Gdy chcesz wywołać wyzwalacz, na przykład gdy w systemie CRM klienta zostanie utworzony potencjalny klient, musisz określić, którą subskrypcję uruchomić po stronie monday.com.

Gdy znajdziesz właściwą subskrypcję, wyślij żądanie POST na powiązany z nią adres webhookUrl:

Metoda: POST

Autoryzacja: token JWT podpisany tajnym kluczem aplikacji, zawierający appId w ładunku JWT.

Przykład: tworzenie tokenu JWT za pomocą jsonwebtoken

const jwt = require('jsonwebtoken');

const appId = 12345; // Your application id from the dev center
const signingSecret = process.env.MONDAY_SIGNING_SECRET;

const jwtToken = jwt.sign({ appId }, signingSecret);

Treść żądania

{
  "trigger" : {
    "outputFields" : {
      "text" : "Hello?",
      "number" : 9
    }
  }
}

import { Storage } from '@mondaycom/apps-sdk';
import jwt from 'jsonwebtoken';

// Initialize storage instance
const storage = new Storage(process.env.MONDAY_TOKEN);

/**
 * Triggers a webhook event for a given subscription
 */
export async function triggerEvent(subscriptionId, data) {
  try {
    const subscriptionString = await storage.get(subscriptionId);

    if (!subscriptionString) {
      throw new Error(`Subscription not found for ID: ${subscriptionId}`);
    }

    const subscriptionData = JSON.parse(subscriptionString);
    const { webhookUrl } = subscriptionData;

    // Create JWT for authorization
    const jwtToken = jwt.sign(
      { appId: process.env.MONDAY_APP_ID },
      process.env.MONDAY_SIGNING_SECRET
    );

    const response = await fetch(webhookUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: jwtToken,
      },
      body: JSON.stringify({
        trigger: {
          outputFields: {
            ...data,
          },
        },
      }),
    });

    if (!response.ok) {
      throw new Error(`Webhook request failed with status: ${response.status}`);
    }
  } catch (error) {
    console.error('Error in triggerEvent:', error);
    throw error;
  }
}

Adres URL anulowania subskrypcji

Twój adres URL anulowania subskrypcji zostanie wywołany, gdy użytkownik usunie Twoją recepturę z przepływu pracy, dezaktywuje ją lub ją skasuje.

Metoda: POST

Treść żądania

{
  "payload": {
    "webhookId": 481709001
  }
}

Nagłówek autoryzacji

Żądanie będzie zawierać token JWT autoryzacji w nagłówkach.

Odpowiedź

Po wywołaniu odpowiedz endpointowi statusem HTTP 200 i bez ładunku. Jeśli zwrócisz błąd, czyli status inny niż 2XX, uniemożliwimy użytkownikowi usunięcie receptury.

Odpowiedź musi też zawierać nagłówek Content-Type:application/json.

Usuń subskrypcję z trwałej pamięci na podstawie przekazanego webhookId.

Słowniczek

Zdarzenia

Zdarzenie subskrypcji: Występuje, gdy użytkownik dodaje Twój wyzwalacz do tablicy lub przepływu pracy w monday. monday wyśle webhook na Twój adres URL subskrypcji.

Zdarzenie anulowania subskrypcji: Występuje, gdy użytkownik usuwa Twój wyzwalacz lub go wyłącza. monday wyśle webhook na Twój adres URL anulowania subskrypcji.

Wywołanie: Proces uruchamiania bloku wyzwalacza. Twoja aplikacja wyśle webhook do monday.

Pola wejściowe: Dane potrzebne do uruchomienia wyzwalacza, zwykle określane przez użytkownika podczas tworzenia integracji.

Pola wyjściowe: Dane przekazywane przez wyzwalacz, zwykle dane i metadane dotyczące zdarzenia.

{/*

Diagram przepływu danych

Poniższy diagram przedstawia niestandardowy wyzwalacz korzystający z webhooka z zewnętrznego systemu CRM.

*/}