> ## Documentation Index
> Fetch the complete documentation index at: https://agenticbanking.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a connector that receives webhooks

> Build a custom connector from the template that receives vendor webhooks and publishes them to Sync Hub

Learn how to build a custom connector from the Grand Central connector template that receives webhook callbacks from an external vendor and publishes them as events to Sync Hub. Use this pattern when a vendor pushes real-time notifications to your endpoint, for example identity verification results or payment status updates.

For the concepts behind this pattern, see [Vendor webhooks](/platform/sync-hub/integration-patterns#1-vendor-webhooks). For field-level detail on envelopes, headers, and properties, see [Sync Hub events and files reference](/platform/sync-hub/events-and-files-reference).

## Prerequisites

Before you start, make sure you have:

* A connector repository scaffolded from the connector template. For more information, see [Set up the project](/platform/developer-guides/build/set-up-the-project).
* Sync Hub deployed in your target runtime, with a topic for your events. For more information, see [Sync Hub deployment and configuration](/platform/sync-hub/deployment).
* The vendor's webhook documentation, including the payload schema and any signature or secret mechanism.
* Java and Maven installed for local builds.

## Build the connector

1. Expose the webhook endpoint. Inbound connectors on Grand Central expose REST endpoints for vendor callbacks, for example `POST /webhooks/identity-verifications`. Define an endpoint path that matches the vendor's callback configuration.

2. Validate incoming requests. Verify the vendor's signature or shared secret before you process the payload, and reject requests that fail validation. Return an acknowledgment status code promptly so the vendor doesn't retry while you process.

3. Transform the vendor payload into your event contract. The event body needs a top-level `data` object. For envelope fields, see [Event envelope](/platform/sync-hub/events-and-files-reference#event-envelope).

4. Set the Sync Hub properties in the connector's `application.properties` file:

   ```properties theme={"system"}
   asb.event.type=com.backbase.party.event.spec.v1.IdentityVerificationEvent
   asb.event.source=com.backbase.party
   asb.event.version=1.0.0
   asb.event.topic=identity-verification
   asb.producer.apiUri=http://asb-producer.synchub-producer.svc.cluster.local
   ```

   The template route builds the publish endpoint as `${asb.producer.apiUri}/${asb.event.topic}/publish` and sets the `bbEventType` header from `asb.event.type`. The template hardcodes the `eventSource` header and derives `eventVersion` from the payload schema. In a production connector, set these headers from your own configuration, for example with the `asb.event.source` and `asb.event.version` properties. Set `identifier` and `traceParent` per request, because they change for each webhook delivery.

   The `asb.event.type` value shown is an example. Use the event spec class that matches your event contract. Confirm the producer release name in the Application manifest for your runtime. Some runtimes deploy a versioned release name such as `asb-producer-v0`.

5. Add the Sync Hub pod labels to the connector's `values.yaml` file so the runtime network policy allows the call to the producer:

   ```yaml theme={"system"}
   connector:
     customLabels:
       app.gcservices.io/synchub-enabled: "true"
       app.gcservices.io/synchub-type: "producer"
   ```

6. Build and run the connector locally:

   ```bash theme={"system"}
   mvn clean verify
   mvn quarkus:dev
   ```

## Verify the connector

To confirm the connector receives webhooks and publishes events:

1. Send a test request to the webhook endpoint locally, for example with `curl`:

   ```bash theme={"system"}
   curl -X POST http://localhost:8080/webhooks/identity-verifications \
     -H "Content-Type: application/json" \
     -d '{"id": "TEST_ID", "status": "COMPLETED"}'
   ```

2. Check the connector logs for successful validation and publish.

3. Check the producer logs in Grafana for the matching publish activity. For queries, see [Logs](/platform/sync-hub/monitoring#logs).

4. Confirm the message arrives on the topic with Azure Service Bus tooling. For more information, see [Service Bus explorer](/platform/developer-guides/run#service-bus-explorer).

5. Register the endpoint URL with the vendor and send a vendor test notification where the vendor supports it.

## Next steps

* [Configure a custom connector](/platform/developer-guides/build/configure-connector): Store the vendor secret with SOPS and set environment-specific properties.
* [Test and validate](/platform/developer-guides/build/test-and-validate): Add automated tests for validation and publish behavior.
* [Sync Hub go-live checklist](/platform/sync-hub/go-live-checklist): Verify your setup before production.