Webhooks

Webhooks enable you to receive notifications or trigger specific actions when certain events occur. Currently, there are two webhooks: Zai and Email.

Webhook deployments require some initial setup. The following is a walkthrough of how to set up each webhook:

1. Zai

To enable Zai webhooks, follow these steps:

1.1. Set Up Zai in Standard Connector

Go to Zai's dashboard and provide the following values: token endpoint, client ID, client secret, scope, and environment.
Generate a webhook secret from the UI by pressing the reload button on the side.
Save or update your settings. Please note that this request might take some time.

1.2. Set Up Webhook URL Host

Specify the webhook URL host.
Press the "Update Webhook" button. Be aware that this request might also take some time.

Now, every time a transaction is successful in your Zai account, all deployments in your instance with domain "webhook" and event "zai webhook" will be triggered.

1.3. Write Scripts

The "webhook" deployments triggered by Zai will receive the following event metadata, which can be accessed using C.getEventMetadata():

{
  "user": {
    "id": -1
  },
  "type": "zai",
  "webhook_uid": "D5LIGvp0BbiBSK2Jd2f3N",
  "webhook_url": "https://6b40-2403-3800-320f-b9d3-158e-a574-1691-d721.ngrok-free.app/api/webhooks/D5LIGvp0BbiBSK2Jd2f3N/capture",
  "object_type": "transactions",
  "zai_webhook_id": "06954bd4-e920-49a4-b297-04067e9ce5b9",
  "description": "Transaction webhook for 131",
  "body": {
    "transactions": {
      "id": "76ece9a0-e3a1-013b-38dd-0a58a9feac03",
      "created_at": "2023-06-02T18:30:25.325Z",
      "updated_at": "2023-06-02T18:30:25.342Z",
      "description": "Credit of $42.00 to Item by Debit of $42.00 from Credit Card",
      "payee_name": null,
      "reference_id": null,
      "type": "payment",
      "type_method": "credit_card",
      "state": "successful",
      "user_id": "16db401f3fd27e1036239c41fe2f6fca",
      "user_name": "Rodney Janover",
      "account_id": "ef772ea0-1118-43bc-b7ba-d9c1bbacd437",
      "account_type": "item",
      "item_name": "Test charge from workflow",
      "dynamic_descriptor": "ASM*229",
      "amount": 4200,
      "currency": "AUD",
      "debit_credit": "credit",
      "marketplace": {
        "group_name": null,
        "name": "HelloMello-Dev",
        "short_name": null,
        "uuid": "7c34bb74-ac4f-484d-90bf-99d4b2eb6319"
      },
      "related": {
        "transactions": [
          {
            "id": "76ecd9d0-e3a1-013b-743b-0a58a9feac03",
            "account_id": "0ac944f0-e32c-013b-725d-0a58a9feac03",
            "account_type": "card_account",
            "user_id": "demo-testing-1",
            "user_name": "Prabhat Test"
          }
        ]
      },
      "links": {
        "self": null,
        "users": "/transactions/76ece9a0-e3a1-013b-38dd-0a58a9feac03/users",
        "fees": "/transactions/76ece9a0-e3a1-013b-38dd-0a58a9feac03/fees",
        "wallet_accounts": "/transactions/76ece9a0-e3a1-013b-38dd-0a58a9feac03/wallet_accounts",
        "card_accounts": "/transactions/76ece9a0-e3a1-013b-38dd-0a58a9feac03/card_accounts",
        "paypal_accounts": "/transactions/76ece9a0-e3a1-013b-38dd-0a58a9feac03/paypal_accounts",
        "bank_accounts": "/transactions/76ece9a0-e3a1-013b-38dd-0a58a9feac03/bank_accounts",
        "items": "/transactions/76ece9a0-e3a1-013b-38dd-0a58a9feac03/items",
        "marketplaces": "/transactions/76ece9a0-e3a1-013b-38dd-0a58a9feac03/marketplaces",
        "npp_payin_transaction_detail": null,
        "supplementary_data": null
      }
    }
  },
  "userId": -1
}

Here's an example of a script that supports Zai webhooks:

async function script(C) {
    const eventMetadata = C.getEventMetadata();
    C.addListsToSummary([
        {
            value: "Got zai webhook. Write code to process metadata...",
            icon: "fa-duotone fa-check",
        },
    ]);
}

2. Email

Email webhooks trigger deployments based on specific email addresses. These email addresses vary between different environments.

📘
Info:
Based on the instance-identifier, all deployments for that instance with domain "webhook" and event "email webhook" are executed.

2.1. Write Scripts

Email webhooks provide the following event metadata, and it's accessible via theC.getEventMetadata():

{
  "user": {
    "id": -1
  },
  "type": "email",
  "emailClient": "sendgrid",
  "logId": 5,
  "attachments": [],
  "subject": "id 1167262",
  "fromName": "Prabhat Pandey",
  "from": "[email protected]",
  "to": [
    "[email protected]"
  ],
  "webhookMetadata": {
    "records": [
      "all-fields"
    ],
    "instance": "clevero"
  },
}

Here's an example of a script that processes email webhooks:

async function script(C) {
    const eventMetadata = C.getEventMetadata();
    C.addListsToSummary([
        {
            value: `Received email webhook from ${eventMetadata.emailClient}`,
            icon: "fa-duotone fa-check",
        },
    ]);
    let entryId;
    try {
        const temp = eventMetadata.subject.split("{{")[1];
        entryId = temp.split("}}")[0].trim();
    } catch {}
    const fieldId = "file-bucket";
    if (entryId) {
        C.addListsToSummary([
            {
                value: `Found ${entryId} in subject. Updating ${fieldId}`,
                icon: "fa-duotone fa-magnifying-glass-location",
            },
        ]);
        await C.updateEntries({
            updates: [
                {
                    entryId: +entryId,
                    recordInternalId: "all-fields",
                    value: {
                        [fieldId]: eventMetadata.attachments,
                    },
                },
            ],        });
    } else {
        C.addListsToSummary([
            {
                value: `Didn't find entry id in subject. Aborting`,
                icon: "fa-duotone fa-magnifying-glass-location",
            },
        ]);
    }
}

📌 Need Help?

If you require assistance or encounter any issues, please don't hesitate to contact us for further support.