Google Cloud (service account)

Google Cloud APIs authenticate with a short-lived OAuth access token. Hooks turns a service-account JSON key file into that token for you, so the generic HTTPS destination can publish to Pub/Sub without a separate adapter.

How the token is obtained

Select Google service account as the destination auth mode and paste the whole key file:

Field	Example	Notes
Service account JSON	{"type":"service_account", …}	The key file from the GCP console; stored as a write-only project secret.
Scope	https://www.googleapis.com/auth/pubsub	Optional; defaults to the Pub/Sub publisher scope.

At delivery time Hooks:

1. Reads client_email, private_key (and private_key_id, token_uri) from the JSON.
2. Signs an RS256 JWT with the claims iss/sub = service-account email, aud = token URI, scope and a one-hour window, using WebCrypto (RSASSA-PKCS1-v1_5, SHA-256).
3. Exchanges it at the token URI with the urn:ietf:params:oauth:grant-type:jwt-bearer grant.
4. Caches the access token until five minutes before expires_in and reuses it for later deliveries to the same account and scope.

A failed exchange fails the attempt with GCP_TOKEN_FAILED before the destination is called. The private key is never returned by the API, written to the console, or recorded on an attempt: the key file is a write-only secret and the authorization header is redacted like any other credential.

Template

Console → Quick start → Any event → Google Cloud Pub/Sub asks for the project id, topic id, an optional ordering key and the source signing secret.

POST https://pubsub.googleapis.com/v1/projects/<project>/topics/<topic>:publish
{
  "messages": [
    {
      "data": "<payload, base64>",
      "attributes": { "event_id": "…", "event_type": "…" },
      "orderingKey": "<optional>"
    }
  ]
}

• data is the raw inbound payload encoded with the base64 template filter, so subscribers read the original bytes.
• attributes carries the Hooks event id and type; add more entries by editing the body template.
• Leave the ordering key blank unless the topic was created with message ordering enabled. When set, every message from this destination uses the same key, so Pub/Sub delivers them in publish order.

Minimal IAM

Create a service account and grant it only the publisher role on the topic:

gcloud pubsub topics add-iam-policy-binding hooks-events \
  --member="serviceAccount:<service-account-email>" \
  --role="roles/pubsub.publisher"

Then create a JSON key for that account (gcloud iam service-accounts keys create key.json --iam-account=…) and paste the file into the template or the auth form.

Troubleshooting

Symptom	Cause	Fix
GCP_TOKEN_FAILED, invalid_grant	Key deleted or revoked, or the client clock is far off.	Create a new key and paste it again.
GCP_TOKEN_FAILED, invalid_scope	Scope does not cover Pub/Sub.	Use https://www.googleapis.com/auth/pubsub or leave the field blank.
403 PERMISSION_DENIED	The account lacks pubsub.topics.publish on the topic.	Add roles/pubsub.publisher as above.
404 NOT_FOUND	Project or topic id is wrong, or the API is disabled.	Check the ids and enable the Pub/Sub API.
400, ordering key rejected	Topic has message ordering disabled.	Clear the ordering key or recreate the topics with ordering enabled.

Related

• Destinations — auth modes, body templates and retries.
• Secrets & rotation — how the key file is stored and rotated.
• Payload templates — the base64 filter and event tokens.