Webhooks

Last updated: February 07, 2024Author: Jakub Pomykała

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

Webhook integration is available in the 'Integrations' 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.

webhook configuration

Sample webhook executions

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

FieldDescription
triggersubscribed trigger type
projectTokenproject token
projectNameproject name, it can be changed in project settings
accountNamename of the user who made a change or started a job.
accountEmailemail of the user who made a change or started a job.
jobIdjob identifier, for example auto-translation job
environmentTranslation Hosting environment key that has been updated
exportedFileLink to exported file, multi-file exports are zipped
changeslist of translation modifications during the change
fileFormatfile format of exported or imported file
customerKeycustomer identifier

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

Possible trigger field values

Trigger valueEvent description
ENVIRONMENT_PUBLICATIONOn publication to Production environment or any custom environment
PUBLICATIONOn publication to Latest environment
CHANGEEvery saved translation change via API, WEB or CLI
REVERTOn reverted translations via WEB
IMPORTOn every file import via WEB, API or CLI
EXPORTOn every file export via WEB, API or CLI
AUTO_TRANSLATION_SUCCESSOn every succeeded auto-translation job started via WEB, API or CLI. jobId will contain finished job identifier
AUTO_TRANSLATION_FAILEDOn every failed auto-translation job started via WEB, API or CLI. jobId will contain failed job identifier

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.

webhook configuration

GitHub Actions

GitHub Actions configuration

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 configuration

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 CI configuration

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 configuration

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 configuration

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 configuration

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.