How to Configure Webhook Secrets and Callback URL

What This Guide Covers

This guide is the practical setup flow for tenant webhook configuration in Backoffice:

• where to put the callback URL,
• where to put the provider secret,
• how Syllecta uses the secret,
• how to test the first delivery,
• how to rotate safely later.

Use this page when a tenant asks:

• "Where do I paste the Stripe signing secret?"
• "Which URL do I give the provider?"
• "Do I need a different secret per environment?"
• "How do I rotate without breaking deliveries?"

Mental Model

For each tenant and provider, Syllecta needs two different things:

1. Inbound verification input
   • the provider secret or signing material used to verify the webhook request that arrives at Syllecta.
2. Outbound destination
   • the callback URL where Syllecta forwards the normalized payload after verification, dedupe, and logging.

These are separate concerns:

• secret proves the inbound webhook is authentic,
• callback URL tells Syllecta where to send the normalized event after it has been accepted.

Before You Start

You need:

• Backoffice access for the tenant,
• the provider you are configuring first:
  • Stripe
  • Shopify
  • GitHub
  • Generic HMAC
  • PayPal / Braintree
• a callback endpoint that can receive POST JSON requests,
• a clear decision on whether you are configuring:
  • production
  • staging
  • local/dev relay

Do not reuse production callback URLs or secrets for staging if you can avoid it.

Step 1. Open the Tenant Webhooks Area

In Backoffice:

1. Open your tenant.
2. Go to Webhooks.
3. Confirm you are editing the correct tenant and environment.

You will usually work in two places:

• Settings for callback URL and tenant-level webhook behavior
• Secrets for provider-specific verification secrets

Step 2. Set the Callback URL

The callback URL is the URL of your service, not the Syllecta inbound endpoint.

Example:

https://api.acme-payments.example/webhooks/syllecta

This URL should:

• accept POST requests,
• accept Content-Type: application/json,
• return any 2xx when processing succeeds,
• be reachable from Syllecta runtime.

Good callback URL characteristics:

• environment-specific
• stable
• owned by the team that processes the normalized event

Avoid:

• temporary personal tunnels for anything beyond local testing,
• callback URLs that redirect,
• callback URLs that return HTML or auth challenges instead of JSON-friendly 2xx/4xx/5xx.

Step 3. Set the Provider Secret

Open Secrets and choose the provider you are integrating.

Examples:

• Stripe: webhook signing secret from the Stripe endpoint configuration
• Shopify: app/shared signing secret used for HMAC verification
• GitHub: webhook secret configured in the GitHub webhook settings
• Generic HMAC: the shared secret you and Syllecta agree on

Store the provider secret exactly as issued by the provider unless the provider documentation explicitly says otherwise.

Do not:

• trim or transform the value yourself,
• paste API keys into secret fields,
• reuse one provider's secret for another provider.

Step 4. Give the Provider the Syllecta Inbound URL

After callback URL and secret are configured, point the provider to Syllecta's inbound endpoint.

Common shapes:

POST /v1/webhooks/:provider
POST /v1/t/:tenantSlug/webhooks/:provider

Use the exact route shown in Backoffice or in your integration docs.

Examples:

https://cloud.syllecta.example/v1/webhooks/stripe
https://cloud.syllecta.example/v1/t/acme-payments/webhooks/generic

Important:

• the provider sends to Syllecta
• Syllecta then forwards to your callback URL

Do not give the provider your callback URL directly if Syllecta is supposed to sit in front of the flow.

How Signature Verification Works

High level flow:

1. Provider sends webhook to Syllecta inbound URL.
2. Syllecta reads the raw request body and signature headers.
3. Syllecta loads the tenant/provider secret from Backoffice.
4. Syllecta verifies the signature according to the provider adapter.
5. If signature is valid:
   • event is deduped,
   • event is logged,
   • normalized payload is forwarded to your callback URL.
6. If signature is invalid:
   • Syllecta rejects the request with 400,
   • nothing is forwarded.

This means:

• the provider secret is used only for inbound authenticity checks,
• your callback URL does not need to know the provider's original signing secret to receive the normalized payload from Syllecta.

Environment Strategy

Use separate configuration per environment whenever possible.

Recommended baseline:

• production tenant or production callback URL
• staging tenant or staging callback URL
• local/dev temporary callback URL only for short-lived testing

If one tenant must carry multiple environments, at minimum keep:

• different callback URLs,
• different provider endpoints/secrets where the provider supports it,
• clear API key labels.

First Test After Setup

Run one controlled webhook after saving configuration.

Suggested order:

1. Save callback URL.
2. Save provider secret.
3. Send one provider test event.
4. Verify in Backoffice:
   • event appears in Webhooks -> Events
   • status reaches processed
5. Verify on your side:
   • callback endpoint received the normalized payload
   • payload shape matches expectations

If the event fails:

1. check the secret first,
2. check the callback URL second,
3. then inspect the event row and failure details.

Security Best Practices

Keep one secret per provider path

Do not share:

• Stripe secret with GitHub,
• production secret with staging if you can avoid it,
• team-internal HMAC secret with external provider verification.

Rotate on a schedule or after any suspicion

Baseline expectation:

• rotate periodically,
• rotate immediately after accidental exposure,
• rotate after access changes if a shared secret had broad visibility.

Use labeled environment ownership

Your team should always know:

• which callback URL belongs to production,
• which secret belongs to staging,
• who owns the receiving callback service.

Test immediately after rotation

Do not rotate and assume it worked.

Always:

1. update secret,
2. send test webhook,
3. confirm processed,
4. confirm downstream callback behavior.

Safe Rotation Flow

Current model is effectively a single active secret per tenant+provider.

Recommended sequence:

1. Prepare the new provider secret in the provider portal.
2. Update the Backoffice secret as close as possible to the provider-side cutover.
3. Send a test webhook immediately.
4. Confirm:
   • signature validation succeeds,
   • delivery succeeds,
   • event appears in Backoffice.
5. If validation fails, revert quickly and repeat carefully.

This is not a dual-secret overlap model, so tight sequencing matters.

Common Setup Mistakes

Giving the provider the callback URL instead of the Syllecta URL

That bypasses Syllecta entirely.

Saving the wrong secret type

Example:

• using a Stripe API key where Stripe expects a webhook signing secret

Forgetting to test after saving

Configuration without a test webhook is not a verified integration.

Reusing one callback URL for multiple environments without clear separation

This creates noisy debugging and ambiguous event ownership.

Troubleshooting Checklist

If events are not reaching your system:

1. Confirm the provider is sending to the Syllecta inbound URL.
2. Confirm the tenant/provider secret is correct.
3. Confirm the callback URL is correct and reachable.
4. Check Webhooks -> Events in Backoffice.
5. Inspect:
   • signature failures,
   • callback failures,
   • repeated retries,
   • wrong tenant/provider mapping.

Related Docs

• Webhook Gateway
• Webhooks API
• Backoffice Overview
• Stripe example
• GitHub example
• Generic HMAC example

This is the tenant-facing setup guide. Use the internal rotation runbook when you need platform-side operational detail rather than customer-facing setup instructions.