Build a connector that receives webhooks

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. For field-level detail on envelopes, headers, and properties, see 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.
• Sync Hub deployed in your target runtime, with a topic for your events. For more information, see Sync Hub deployment and configuration.
• 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.
4. Set the Sync Hub properties in the connector’s application.properties file:
   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:
   connector:
     customLabels:
       app.gcservices.io/synchub-enabled: "true"
       app.gcservices.io/synchub-type: "producer"
   
6. Build and run the connector locally:
   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:
   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.
4. Confirm the message arrives on the topic with Azure Service Bus tooling. For more information, see 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: Store the vendor secret with SOPS and set environment-specific properties.
• Test and validate: Add automated tests for validation and publish behavior.
• Sync Hub go-live checklist: Verify your setup before production.