Webhooks

Webhooks allow external services to be notified when certain events happen. When the specified events happen, we’ll send a POST request to each of the URLs you provide.

Table of contents

• How to set up webhooks

• Examples

  • List of fields in webhook payload
  • Possible trigger field values

• Webhook types

  • Default
  • GitHub Actions
  • GitLab CI
  • Bitbucket Pipelines
  • Slack
  • Discord
  • Microsoft Teams

How to set up webhooks

Webhook integration is available in the 'Settings' tab under 'Webhooks' section. To set up webhooks, click 'Add webhook'. Then, fill in the form and click 'Add webhook'. Every webhook invocation is registered, so you can check the history of webhook invocations, execution time, execution URL, trigger, response status code and body.

Examples

Sample webhook payload triggered by translation editor changes.

{
  "trigger": "CHANGE",
  "projectToken": "94a08da1fecbb6e8b46990538c7b50b2",
  "projectName": "My project",
  "accountName": "Jakub",
  "accountEmail": "[email protected]",
  "changes": [
    {
        "action": "CREATE_KEY",
        "key": "hello-world"
    },
    {
        "action": "CHANGE_TRANSLATION",
        "key": "hello-world",
        "languageKey": "en",
        "newTranslation": "Hello World!"
    },
    {
        "action": "CHANGE_KEY",
        "oldKey": "hello-world",
        "newKey": "goodbye-world"
    },
    {
        "action": "DELETE_KEY",
        "key": "goodbye-world"
    }
  ]
}

Sample webhook payload triggered on auto-translation success.

{
  "trigger": "AUTO_TRANSLATION_SUCCESS",
  "projectToken": "94a08da1fecbb6e8b46990538c7b50b2",
  "projectName": "My project",
  "accountName": "Jakub",
  "accountEmail": "[email protected]",
  "jobId": "69b569c0e04e1b955c1e14c52e02665f",
  "changes": [
    {
        "action": "CHANGE_TRANSLATION",
        "key": "hello-world",
        "languageKey": "en",
        "newTranslation": "Hello World!"
    }
  ]
}

Sample webhook payload triggered on production environment publication.

{
  "trigger": "ENVIRONMENT_PUBLICATION",
  "projectToken": "94a08da1fecbb6e8b46990538c7b50b2",
  "projectName": "My project",
  "accountName": "Jakub",
  "accountEmail": "[email protected]",
  "environment": "_production",
  "changes": []
}

Sample webhook payload triggered on any custom environment publication.

{
  "trigger": "ENVIRONMENT_PUBLICATION",
  "projectToken": "94a08da1fecbb6e8b46990538c7b50b2",
  "projectName": "My project",
  "accountName": "Jakub",
  "accountEmail": "[email protected]",
  "environment": "custom-environment",
  "changes": []
}

Sample webhook payload triggered on latest environment publication.

{
  "trigger": "PUBLICATION",
  "projectToken": "94a08da1fecbb6e8b46990538c7b50b2",
  "projectName": "My project",
  "accountName": "Jakub",
  "accountEmail": "[email protected]",
  "changes": []
}

List of fields in webhook payload

Please keep in mind that request body fields may be extended in the future, but they won't change.

Possible trigger field values

Webhook URL cannot contain IP addresses, localhost domain, or SimpleLocalize API. It must be a valid URL. URL must respond to a HEAD request to be added.

Webhook types

SimpleLocalize supports multiple webhook types that are pre-configured for certain services like Slack, Discord, and GitHub Actions to make integration easier.

Default

Default webhook type is a simple webhook that sends a POST request to the specified URL with defined headers a JSON payload presented above.

GitHub Actions

GitHub Actions type is a webhook prepared to send a POST request that dispatches a workflow event with the following request body:

{
  "event_type": "simplelocalize_environment_publication",
  "client_payload": {
    "trigger": "ENVIRONMENT_PUBLICATION",
    "projectToken": "94a08da1fecbb6e8b46990538c7b50b2",
    "projectName": "My project",
    "accountName": "Jakub",
    "accountEmail": "[email protected]",
    "environment": "_production",
    "changes": []
  }
}

Dispatch requires GitHub Personal Access Token with repo scope.

The event_type field is a combination of simplelocalize_ and lower case trigger value.

name: SimpleLocalize GitHub Action
on:
  repository_dispatch:
    types:
      - simplelocalize_environment_publication
      - simplelocalize_change

You can access fields from client_payload in your workflow using the following syntax:

${{ github.event.client_payload.projectToken }}

Read more about executing GitHub Workflow via Webhooks and uploading Translation Hosting resources to S3 with GitHub Actions.

GitLab CI

GitLab CI type is a webhook that triggers a GitLab CI pipeline for a specified project and branch. Trigger requires GitLab pipeline trigger token that can be generated in your GitLab project settings.

Variables available in the pipeline:

• simplelocalize_trigger
• simplelocalize_project_token
• simplelocalize_project_name
• simplelocalize_account_name
• simplelocalize_account_email
• simplelocalize_environment
• simplelocalize_exported_file
• simplelocalize_job_id

Bitbucket Pipelines

Bitbucket Pipelines type is a webhook that runs a Bitbucket Pipelines pipeline for a specified repository and branch. Trigger requires Authorization header with Bearer {token} to authenticate. Forge app token can be generated in your Bitbucket account settings, and you need to add the following scopes:

• read:pipeline:bitbucket
• write:pipeline:bitbucket

Variables available in the pipeline:

• simplelocalize_trigger
• simplelocalize_project_token
• simplelocalize_project_name
• simplelocalize_account_name
• simplelocalize_account_email
• simplelocalize_environment
• simplelocalize_exported_file
• simplelocalize_job_id

Slack

Slack type is a webhook prepared to send a POST request to

https://hooks.slack.com/services/{webhook}

with a predefined message for each trigger type. Learn how to get a Slack webhook URL.

Discord

Discord webhook type is a webhook prepared to send a POST request to the

https://discord.com/api/webhooks/{webhook}

with a predefined message for each trigger type. Learn how to get a Discord webhook URL.

Microsoft Teams

Microsoft Teams webhook type is a webhook that is prepared to send a POST request to

https://{team}.outlook.office.com/webhookb2/{webhook}

with a predefined message for each trigger type. Learn how to get a Microsoft Teams webhook URL.

Requests sent to Microsoft Teams takes about 10–30 seconds to be processed and delivered to the channel.