Integrations
CI
The gate in a pipeline is validate — every other command is a read and does not fail a build.
# .github/workflows/translations.yml
name: translations
on: [push, pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
with: { php-version: '8.3' }
- run: composer global require babelhub/cli:~0.1.0
- run: babelhub validate --fail-on=error
env:
BABELHUB_TOKEN: ${{ secrets.BABELHUB_TOKEN }}
BABELHUB_TOKEN is a personal token (pat_…) or an application key; the credential never
goes into .babelhub.json, because that file belongs in the repository and goes through review.
Exit codes: 0 success, 1 the tool could not finish, 6 a check failed, 124 a hook timed
out. 6 and 1 are separate on purpose — otherwise "the translations are wrong" looks like
"the tool broke".
Webhooks
Panel → Webhooks. The signing secret is shown once, when the subscription is created.
Every request carries:
X-BabelHub-Signature: t=<unix>,v1=<HMAC_SHA256(secret, t + "." + body)>
Same scheme as Stripe, so there is nothing new to learn. Verification:
- reject the request if
tis older than 5 minutes (otherwise a captured request can be replayed forever); - compute the HMAC over
t + "." + bodyand compare in constant time; - drop duplicates by
event_id— delivery is at least once.
Delivery: 5 attempts with exponential backoff, then failed and a visible retry in the panel.
Every attempt is in the history with the receiver's response code, so "the webhook does not
work" is never a report without data.
Payloads for bulk events are deliberately small: key.removed, import.finished and
sync.finished carry a revision id, not a list of objects — the receiver fetches details from a
paginated endpoint. A webhook that tries to deliver 5 000 keys will not fit the time window and
will be reported as our outage.
Every subscription has a "Send test" button — the cheapest way to check an integration without contacting support.
Git
The project configuration (.babelhub.json) belongs in the repository; the credential lives
outside it (environment variables in CI, a credential store locally). The configuration file says
what to synchronize, not who you are — mixing the two ends with a secret in git history.