Go to Lokalise
All Collections
Integrations
Notifications and events
Webhooks

Webhooks

Custom webhook integration.
Andrew avatar
Written by Andrew
Updated over a week ago

Use webhooks to receive instant notifications about events happening in Lokalise as POST requests. 

The webhook is sent once an event happens and it expects an answer from your side with a 2xx status code. We do not sign the requests, so you may want to restrict the incoming requests from IP's 159.69.72.82, 94.130.129.39, 195.201.158.210 and 94.130.129.237.

To set up the integration for your project:

  1. Navigate to Project settings > Integrations

  2. Click Connect button for the Webhook integration

  3. Enter configuration parameters: URL to send events to and the branch (if the branching is enabled for your project)

  4. Select desired events

  5. Click Enable integration

Webhook secret

Webhook secret is generated for you automatically once the integration is enabled. The secret is represented as a random alphanumeric string:

The secret is sent to the specified webhook with each request. By checking the secret's value you can make sure the request is not coming from a malicious source.

The secret may be regenerated any time. To do that, open Project settings > Integrations > Webhooks, find the desired webhook and click on the Refresh icon:

Changes

We've completely rewritten webhook implementation. Projects, where the old webhook system was used will have a Webhooks (legacy) integration, which is documented here. Here is what's new in current version:

  • You can subscribe and unsubscribe from webhooks programmatically, using our API.

  • Retry mechanism (see below).

  • Secret is sent in header, so you can validate the request.

  • Payload for some events has been updated.

Requirements

  • Accept POST requests

  • Return 2xx  status code (200, 201, 202 etc.)

Retry mechanism

In case webhook was not sent our system will retry to re-send it up to 4 times:

  • in ± 10 minutes, after initial retry.

  • in ± 40 minutes, after initial retry.

  • in ± 3 hours, after initial retry.

  • and in ± 24 hours, after initial retry.

Each webhook is independent and is sent separately.

Available webhook events

  • project.imported 

  • project.exported 

  • project.deleted

  • project.snapshot 

  • project.languages.added 

  • project.language.removed  

  • project.language.settings_changed 

  • project.key.added 

  • project.key.modified 

  • project.keys.deleted 

  • project.key.comment.added 

  • project.translation.updated 

  • project.translation.proofread 

  • project.contributor.added 

  • project.contributor.deleted 

  • project.task.created 

  • project.task.closed 

  • project.task.deleted 

  • project.task.language.closed 

  • project.task.initial_tm_leverage.calculated

  • team.order.created

  • team.order.completed

  • team.order.deleted

Webhook payload examples

  • project.imported:

{
  "event": "project.imported",
  "import": {
    "filename": "en.json",
    "format": "json",
    "inserted": 231,
    "updated": 0,
    "skipped": 0
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.exported:

{
  "event": "project.exported",
  "export": {
    "type": "json",
    "filename": "files/export/138c1ffa0ad94848f01f980e7f2f2af19d1bd553/67d1a7ff9cab3a57e32ea71c4561a58d/locales.zip",
    "platform": "Web"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.deleted:

{
  "event": "project.deleted",
  "project": {
    "id": "123.abc",
    "name": "Sample project"
  },
  "user": {
    "full_name": "John Doe",
    "email": "joh.doe@example.com"
  },
  "created_at => "2019-07-29 12:18:31",
  "created_at_timestamp => 1564395511
}

  • project.snapshot:

{
  "event": "project.snapshot",
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.languages.added:

{
  "event": "project.languages.added",
  "languages": [
    {
      "id": 734,
      "iso": "it",
      "name": "Italian"
    }
  ],
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.language.removed:

{
  "event": "project.language.removed",
  "language": {
    "id": 734,
    "iso": "it",
    "name": "Italian"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.language.settings_changed:

{
  "event": "project.language.settings_changed",
  "language": {
    "id": 734,
    "iso": "it",
    "name": "Italian"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.key.added:

{
  "event": "project.key.added",
  "key": {
    "id": 16307699,
    "name": "test.title",
    "base_value": "Hello, world!"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.key.modified:

{
  "event": "project.key.modified",
  "key": {
    "id": 16307699,
    "name": "test.title_modified",
    "previous_name": "test.title"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.keys.deleted:

{
  "event": "project.keys.deleted",
  "keys": [
    {
      "id": 16307699,
      "name": "test.title_modified"
    },
    {
      "id": 16307700,
      "name": "test.to_delete"
    }
  ],
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.key.comment.added:

{
  "event": "project.key.comment.added",
  "comment": {
    "value": "My comment to test.title key"
  },
  "key": {
    "id": 16307701,
    "name": "test.title",
    "filenames": {
      "android": "filename1",
      "ios": "filename2",
      "other": "filename3",
      "web": "filename4"
    }
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.translation.updated:

{
  "event": "project.translation.updated",
  "translation": {
    "id": 84835169,
    "value": "Hello, %s!",
    "previous_value": "Hi!"
  },
  "language": {
    "id": 640,
    "iso": "en",
    "name": "English"
  },
  "key": {
    "id": 16307701,
    "name": "test.title"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.translation.proofread:

{
  "event": "project.translation.proofread",
  "translation": {
    "id": 84835169,
    "value": "Hello, %s!",
    "is_proofread": true
  },
  "language": {
    "id": 640,
    "iso": "en",
    "name": "English"
  },
  "key": {
    "id": 16307701,
    "name": "test.title"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.contributor.added:

{
  "event": "project.contributor.added",
  "contributor": {
    "email": "contributor@mycompany.com"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.contributor.deleted:

{
  "event": "project.contributor.deleted",
  "contributor": {
    "email": "contributor@mycompany.com"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.task.created:

{
  "event": "project.task.created",
  "task": {
    "id": 5022,
    "type": "translation", // supported types are "translation" and "review"
    "title": "Headings translation",
    "due_date": "2019-08-01 00:00:00",
    "description": "Task description"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.task.closed:

{
  "event": "project.task.closed",
  "task": {
    "id": 5022,
    "type": "translation", // supported types are "translation" and "review"
    "title": "Headings translation",
    "due_date": "2019-08-01 00:00:00",
    "description": "Task description"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.task.deleted:

{
  "event": "project.task.deleted",
  "task": {
    "id": 5022,
    "title": "Headings translation",
    "due_date": "2019-08-01 00:00:00",
    "description": "Task description"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • project.task.language.closed:

{
  "event": "project.task.language.closed",
  "language": {
    "id": 640,
    "iso": "en",
    "name": "English"
  },
  "task": {
    "id": 5022,
    "type": "translation", // supported types are "translation" and "review"
    "title": "Headings translation",
    "due_date": "2019-08-01 00:00:00",
    "description": "Task description"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "jdoe@mycompany.com",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

  • team.order.created:

{
    "event": "team.order.created",
    "project": {
        "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
        "name": "TheApp Project"
    },
    "order": {
        "id": "20101010D85",
        "provider": "lokalise",
        "currency": "USD",
        "total": 10.00
    },
    "user": {
        "email": "jdoe@mycompany.com",
        "full_name": "John Doe"
    },
    "created_at": "2019-07-29 12:18:31",
    "created_at_timestamp": 1564395511
}

  • team.order.deleted:

{
  "event": "team.order.deleted",
  "project": {
    "id": "123.abc",
    "name": "Sample project"
  },
  "user": {
    "full_name": "John Doe",
    "email": "john.doe@example.com"
  },
  "created_at => "2019-07-29 12:18:31",
  "created_at_timestamp => 1564395511
}

  • team.order.completed:

{
    "event": "team.order.completed",
    "project": {
        "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
        "name": "TheApp Project"
    },
    "order": {
        "id": "20101010D85",
        "provider": "lokalise"
    },
    "created_at": "2019-07-29 12:18:31",
    "created_at_timestamp": 1564395511
}

  • project.task.initial_tm_leverage.calculated:

{
  "event": "project.task.initial_tm_leverage.calculated",
  "task": {
    "id": 12345,
    "title": "New task",
    "description": "Please translate as soon as possible",
    "initial_tm_leverage": {
      "600": {
        "0": 154,
        "50": 5,
        "75": 4,
        "85": 11,
        "95": 0,
        "100%": 6
      },
      "1056": {
        "0": 158,
        "50": 17,
        "75": 0,
        "85": 0,
        "95": 2,
        "100%": 3
      }
    }
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "created_at": "2021-03-30 16:01:11",
  "created_at_timestamp": 1617112871
}

Receiving webhooks in PHP (example)

$input = @file_get_contents("php://input");
$data = json_decode($input, true);
http_response_code(200);
Did this answer your question?