Best Practices & Troubleshooting

Best Practices

1. Always Verify Signatures

Never process a webhook event without first verifying the X-Signature header. This ensures:

• The request genuinely came from Novee.
• The payload has not been tampered with in transit.
• The request is not a replay of a previously intercepted message.

2. Respond Quickly

Return a 2xx HTTP status code as quickly as possible. Offload any heavy processing to a background queue or worker.

✅ Receive → Verify → Acknowledge (200) → Process async
❌ Receive → Verify → Process (slow) → Acknowledge (200)

If your endpoint does not return a 2xx response, the delivery is considered failed.

3. Use HTTPS

Always use an https:// URL for your webhook endpoint. The Novee API validates your URL at registration time, so only valid URLs are accepted.

4. Handle Duplicate Events

In rare cases (e.g., network issues, retries), you may receive the same event more than once. Design your webhook handler to be idempotent:

• Track processed events by their content/timestamp.
• Use a deduplication strategy that suits your use case.

5. Subscribe Only to What You Need

Only subscribe to the event types you actually need. This reduces unnecessary traffic and processing load.

6. Store Your Secret Securely

• Use environment variables or a secrets manager.
• Never log or expose your webhook secret.
• Never commit it to version control.

7. Monitor Your Endpoint

Set up monitoring and alerting for your webhook endpoint to detect:

• High error rates or non-2xx responses.
• Increased latency in response times.
• Unexpected downtime.

Error Handling

Registration Errors

Delivery Errors

Update Errors

Troubleshooting

”I’m not receiving any webhooks”

1. Check registration: GET /webhooks/project/:projectId — confirm a webhook exists.
2. Check event types: Ensure the events you expect are in the types array.
3. Check your URL: Make sure your endpoint is publicly accessible and returns 2xx.
4. Send a test: Use POST /webhooks/test/project/:projectId to trigger a test event.
5. Check server logs: Look for incoming requests from the Novee platform.

”Signature verification is failing”

1. Use the raw body: Ensure you’re using the raw request body string, not a re-serialized or parsed version.
2. Check your secret: Confirm you’re using the correct whsec_... secret from registration.
3. Check timestamp: Ensure your server clock is synchronized. The timestamp tolerance is 5 minutes.
4. String construction: The signing string is {timestamp}.{raw_body} — ensure there’s no extra whitespace.

”I get ‘Webhook has already been registered previously’”

Each project can only have one webhook. To change it:

• Update: PATCH /webhooks with the new URL or types.
• Replace: DELETE /webhooks/project/:projectId, then POST /webhooks/register.

”I need to rotate my webhook secret”

The current API does not support secret rotation. To get a new secret:

1. Delete the existing webhook: DELETE /webhooks/project/:projectId
2. Re-register: POST /webhooks/register
3. Update your server with the new secret.

Note: There will be a brief period during re-registration where events are not delivered.

Summary of Endpoints