Webhook

The Webhook module allows Crowdin Apps to listen for specific events and trigger actions when those events occur. This module is useful for automating workflows (e.g., work in combination with Workflow Step Type module), synchronizing external systems, or logging project activities.

Structure

manifest.json

{
  "modules": {
    "webhook": [
      {
        "key": "webhook-key-module-key",
        "url": "/webhooks",
        "events": [
          "project.translated",
          "project.approved"
        ],
        "environments": [
          "crowdin",
          "crowdin-enterprise"
        ]
      }
    ]
  }
}

Properties

key	Type: string Required: yes Description: Module identifier within the Crowdin app.
url	Type: string Required: yes Description: The relative URL of the webhook handler in the app.
events	Type: array Required: yes Description: A list of events that trigger the webhook. See the list of available webhook events.
environments	Type: string Allowed values: crowdin, crowdin-enterprise Description: Set of environments where a module could be installed. This parameter is needed for cross-product applications.

Communication between App and Crowdin

All webhooks are triggered via an HTTP POST request with a JSON-formatted payload. The request may contain a single event or multiple events (always delivered in bulk mode).

Read more about Webhook Payload Examples.

Request to the App

When an event occurs, Crowdin sends an HTTP POST request to your webhook endpoint, complete with necessary headers for authentication and security. Below is an example of such a request.

HTTP request:

POST /webhooks HTTP/1.1
User-Agent: Crowdin-Webhook
Content-Type: application/json
X-Crowdin-Id: <organization-id>
X-Crowdin-Domain: <organization-domain>
X-Crowdin-Signature: <signature>
X-Module-Key: <your-module-key>

Request Body:

{
  "events": [
    {
      "event": "project.translated",
      "project": {
        "id": "777",
        // ...
      },
      "targetLanguage": {
        "id": "uk",
        // ...
      }
    },
    {
      "event": "project.approved",
      "project": {
        "id": "777",
        // ...
      },
      "targetLanguage": {
        "id": "uk",
        // ...
      }
    }
  ]
}

During the app installation process, a unique secret called the app_secret is provided to your app. This secret is used to generate the webhook signature using the HMAC algorithm with SHA-256.

Expected Response from the App

Crowdin expects your app to respond with a successful HTTP status code (i.e., any 2XX status) to acknowledge receipt of the webhook payload.