Webhooks (also called "HTTP Callbacks" or "HTTP Push") are a way of sending real-time HTTP notifications to the endpoints you provide. The SupaRes API offers a robust webhook delivery system you can leverage right away.

When using Webhooks as your response method of choice, the API will immediately return a unique request id with status code 202 Accepted for every call. Once the processing of your request on our backend is complete, the API will POST a full JSON response to the Webhook endpoint you provided in your request. That notification will also include the same id parameter you received with your initial API call so you can easily pair your requests with Webhook notifications.

Configuring Webhook Delivery

To use Webhooks as a response method, the JSON request must include a webhook hash with a mandatory url parameter. That URL will be used as a Webhook endpoint and will instruct the API to send a full JSON response to that URL. Optionally you may also include a delay parameter which takes an integer between 1 - 86400 and sets the number of seconds after which the notification will be sent. By default, delay is set to 0 meaning the Webhook will be delivered immediately after the processing is finished.

{
    "webhook": {
        "url": "https://www.website.com/endpoint",
        "delay": 60
    }
}

Example Webhook Flow

Let's take a look at an example flow when using Webhooks. We'll use the Image Fetch method (provide an image URL) and upscale that image by a factor of 4. First we make a request to the API and include the webhook hash:

curl https://api.supares.com/1.0/fetch -X POST -u your-api-key: \
-H "Content-Type: application/json" \
-d '{
    "url": "https://www.website.com/image.jpg",
    "upscale": {
        "factor": 4
    },
    "webhook": {
        "url": "https://www.website.com/endpoint"
    }
}'

The API immediately responds with 202 Accepted and sends a request id in the response JSON:

HTTP/1.1 202 ACCEPTED

{
    "success": true,
    "code": 202,
    "id": "f26656d4-3322-4279-acf4-0e1b3ef9d4bd"
}

After the processing is finished the API delivers a POST notification to your endpoint with full JSON metadata. Please make sure that the id property in the notification matches the initial request id you received when calling the API.

{
    "success": true,
    "code": 200,
    "id": "f26656d4-3322-4279-acf4-0e1b3ef9d4bd",
    "input": {
        ...
    },
    "output": {
        ...
    }
}

Receiving a Webhook Notification

Your endpoints must respond to a Webhook notification within 10 seconds with a 200 OK status code. Responses that take longer than 10 seconds will be treated as a failure. All response codes outside of 2xx range, including 3xx codes, will also indicate that you did not receive the webhook. That means that a URL redirection or a "Not Modified" response will be treated as a failure.

Webhooks will come from the following IP address range: 212.224.84.128/26. You may refuse other IP addresses from your endpoint configuration.

Cross Site Request Forgery (CSRF)

Many applications use CSRF protection as an important security measure to prevent cross-site request forgery attempts. Unfortunately that mechanism will also prevent SupaRes Webhooks from hitting your endpoints. You must disable forgery protection for the routes you set up to listen for events from SupaRes.