API Reference

Auto provisioning with webhooks

The most common use case for webhooks is provisioning and deactivating user accounts based on that user's invoice status.

Use webhooks to receive updates on events in Aqueduct. Each time an event that you subscribed to occurs, Aqueduct submits a POST request to the designated webhook URL with information about the event.

Creating a webhook

  1. Get your API keyLogin to the Aqueduct Dashboard and fetch/generate your API key from the settings page
  2. Identify the relevant events you'd like to subscribe to Here's our list of supported webhook events.
  3. Create a webhook using the webhooks endpoint API You can use the curl request below, just make sure you properly substitute in your API key, URL, and secret. Events you want to be subscribed to should be passed in under "enabledEvents"
curl --location \
--request POST 'https://api.tryaqueduct.com/v1/webhookendpoints' \
--header 'Authorization: Api-Key <insert-api-key-here>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "<insert-your-webhook-url-here>",
    "enabledEvents": ["provisioning_start", "provisioning_end"],
    "secret": "<insert-your-secret-here>"
}'

If you registered the webhook successfully, you should be able to see it in the settings page:

Testing and responding to webhooks

For development purposes, we suggest you use ngrok. Ngrok allows you to replay any incoming request so you can replay the Aqueduct webhook post-event over and over during testing instead of having to re-trigger the event.

  1. Create a webhook endpoint as an HTTP endpoint in your backend. When an event you are monitoring is triggered, Aqueduct will call this endpoint with a POST request and deliver the data as a JSON payload.

  2. Trigger a test webhook request to test the integration. You can do this on the Settings page by clicking the “send test event” button next to your webhook.

  3. Implement logic handling the webhook in your backend. Once you receive the payload, you can run whatever logic is suitable for you app. For example, you want want to provision your customer's access to your product after the product is mark as paid. Please a 2xx respond status code before running any complex logic so the request doesn't time out.

    You can see an example of the provisioning object in the 200 response here.

  1. Trigger the webhook event you're planning on using. For example, if you're developing against invoice.paid, create a test Invoice in the dashboard and manually mark it as paid.

Aqueduct will retry events up to 4 times for 3xx, 4xx, and 5xx response codes with a 1 hour, 6hr, 12hr, and 24hr delay. After all 4 events are attempted, we will email you about the failure and stop attempting this webhook. You can go back into the dashboard to turn on disabled webhooks.