ZartsAlgo

Connector implementation

Google Business Profile Webhook Intake Plan

Google Business Profile webhook intake plan for ZartsAlgo admin, portal, reporting, and integration runtime. Receive provider events with dedupe keys, payload summaries, retry state, and dead-letter handling.

Request implementation audit Back to library

Implementation model

Build the connection as an operating system, not a one-off script.

Each connector needs admin ownership, database mapping, failure handling, and a client-safe proof story before it becomes part of the portal.

Provider

Start with a named provider

Google Business Profile should have a provider key, connection status, owner, and clear reason for being connected.

Runtime

Choose the runtime boundary

Use the primary app database for clean business records and the traffic database for high-volume raw events or webhook summaries.

Owner

Assign a human owner

Integration owner owns setup, verification, incident response, and the client-facing summary.

Mapping

Normalize before reporting

Provider fields should be mapped into ZartsAlgo records before reports, portal cards, or automations depend on them.

Proof

Show client-safe movement

The portal should show source, baseline, current value, status, and next action without exposing raw payloads.

Recovery

Plan rollback and retries

Every connector needs retry rules, dead-letter handling, and a manual fallback for important client updates.

Tables

Primary tables involved.

These are the first tables to check when implementation moves from planning to MySQL-backed code.

  • integration_provider_accounts
  • integration_import_batches
  • metric_snapshots
  • crm_lead_sources
  • integration_providers
  • integration_connections
  • integration_sync_jobs
  • integration_sync_runs
  • integration_sync_errors
  • integration_field_mappings
  • integration_raw_events
  • integration_normalized_events

Checklist

Steps before this is live.

  • Create or confirm the integration provider record.
  • Create a connection record with client, provider account ID, environment, and status.
  • Document auth type, scopes, credential storage, refresh needs, and revocation path.
  • Add sync job or webhook event names before processing live data.
  • Map external object types to internal tables and fields.
  • Run a small test batch and record records seen, created, updated, and failed.
  • Create a baseline before the connector changes reports or automations.
  • Define what the client is allowed to see in the portal.
  • Add monitoring for stale syncs, rate limits, failed webhooks, and duplicate events.
  • Keep a manual import path until the connector has proven reliability.

Client proof

Signals this can safely feed.

Metrics should become report notes, portal cards, admin tasks, or incident alerts. Raw provider data stays internal.

Metric

profile calls

Track this signal only when source, period, unit, and client meaning are clear.

Metric

website clicks

Track this signal only when source, period, unit, and client meaning are clear.

Metric

messages

Track this signal only when source, period, unit, and client meaning are clear.

Metric

direction requests

Track this signal only when source, period, unit, and client meaning are clear.

Timeline

Implementation checkpoints.

Access

Access checkpoint

Confirm account access, provider docs, auth model, and required scopes.

Connection

Connection checkpoint

Create provider and connection records, then store credentials outside public code.

Mapping

Mapping checkpoint

Map objects, fields, statuses, and metric names into ZartsAlgo tables.

Test

Test checkpoint

Run a test sync or webhook and review created, updated, failed, duplicate, and ignored records.

Report

Report checkpoint

Create the client-safe baseline/current explanation and the next action.

Monitor

Monitor checkpoint

Watch stale syncs, rate limits, errors, and portal visibility after launch.

Avoid

Things that break trust.

  • Do not store provider tokens in public PHP files or in readable JSON records.
  • Do not merge different lead sources without source labels.
  • Do not overwrite a baseline with a partial sync.
  • Do not show raw accounting, CRM, phone, or marketplace payloads to clients.
  • Do not treat webhook delivery as proof that the normalized record was created.
  • Do not give the runtime app user schema-changing privileges.
  • Do not launch without an owner, last-tested date, and failure path.
  • Do not let provider-specific language leak into generic client reports.