Implementing your webhook-endpoints

Best Practices

When implementing your webhook endpoint, please follow these best practices:

• Do not perform lengthy processing before returning a 2XX response: Instead, save the event for later processing or enqueue it on a message bus, and return 2XX immediately. It is essential to avoid congesting Spark webhook endpoint calls. This also ensures you avoid timeouts by quickly acknowledging receipt of the event and ensuring we do not retry and send the event more than once. This is also how GitHub recommends handling webhook events.

• Always return a 2XX response: This is important to acknowledge receiving the event.

• Handle retries: If your endpoint returns a status code other than 2XX, the event will be retried up to three times with an exponential backoff strategy. If the event is not successfully delivered after three retries, there are no further attempts to deliver it. You can still fetch it via the /events endpoint. Make sure you handle duplicate events in your system to avoid processing the same event multiple times.

• Verify signature: Preferably, use the webhookSecret you provided during webhook registration to verify the event’s signature. This will ensure the integrity and origin of the event coming from Spark so that you can trust it.

Tip

Our partner reference repository contains generated reference code for webhook servers which can receive webhook notifications sent by Spark, along with API clients which can interact with the API. Also see the this documentation page for more details.

Code generation from OpenAPI

The API specification is available in the Swagger UI and as an OpenAPI 3.0 file here.

You can use tools like OpenAPI Generator or Swagger Codegen to generate types (and, in some cases, API implementation) from your favorite language. This will help you work with the API in a strongly typed manner.