oauthWebhookCreate

Subscribe to webhook events from an OAuth client context. Use this mutation when your application authenticates via the authorization code flow (3-legged OAuth) and needs to receive webhook notifications scoped to the authorized organization.

Required scope: edit_integrations

---

Mutation

mutation OauthWebhookCreate($input: IntegrationWebhookInput!) {
  oauthWebhookCreate(input: $input) {
    id
    type
    health
    endPoint
  }
}

---

Input — IntegrationWebhookInput

Field	Type	Required	Description
endPoint	String	✅	HTTPS URL that will receive webhook POST requests
type	String	✅	Event type to subscribe to (e.g. "order/created")
headers	JSON	❌	Custom HTTP headers to include in every webhook delivery

The endPoint must use HTTPS. HTTP endpoints are rejected. The headers field accepts a JSON object for passing custom authentication or routing headers to your endpoint.

---

Example Variables

{
  "input": {
    "endPoint": "https://my-saas.example.com/hooks/happycolis",
    "type": "delivery_order/completed",
    "headers": {
      "X-Api-Key": "my-saas-api-key"
    }
  }
}

---

Example Response

{
  "data": {
    "oauthWebhookCreate": {
      "id": "wh_660f9500-f3ac-52e5-b827-557766551111",
      "type": "delivery_order/completed",
      "health": "HEALTHY",
      "endPoint": "https://my-saas.example.com/hooks/happycolis"
    }
  }
}

---

Code Examples

curl

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "mutation OauthWebhookCreate($input: IntegrationWebhookInput!) { oauthWebhookCreate(input: $input) { id type health endPoint } }",
    "variables": {
      "input": {
        "endPoint": "https://my-saas.example.com/hooks/happycolis",
        "type": "delivery_order/completed",
        "headers": { "X-Api-Key": "my-saas-api-key" }
      }
    }
  }'

Node.js

async function createOauthWebhook(accessToken, input) {
  const response = await fetch('https://api-v3.happycolis.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      query: `
        mutation OauthWebhookCreate($input: IntegrationWebhookInput!) {
          oauthWebhookCreate(input: $input) {
            id
            type
            health
            endPoint
          }
        }
      `,
      variables: { input },
    }),
  });

  const { data, errors } = await response.json();
  if (errors) throw new Error(errors[0].message);
  return data.oauthWebhookCreate;
}

const webhook = await createOauthWebhook(process.env.ACCESS_TOKEN, {
  endPoint: 'https://my-saas.example.com/hooks/happycolis',
  type: 'delivery_order/completed',
  headers: { 'X-Api-Key': 'my-saas-api-key' },
});

console.log(`Webhook registered: ${webhook.id}`);

Python

import os
import requests

def create_oauth_webhook(access_token: str, input_data: dict) -> dict:
    mutation = """
    mutation OauthWebhookCreate($input: IntegrationWebhookInput!) {
      oauthWebhookCreate(input: $input) {
        id
        type
        health
        endPoint
      }
    }
    """
    response = requests.post(
        'https://api-v3.happycolis.com/graphql',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
        },
        json={'query': mutation, 'variables': {'input': input_data}},
    )
    result = response.json()
    if 'errors' in result:
        raise Exception(result['errors'][0]['message'])
    return result['data']['oauthWebhookCreate']

webhook = create_oauth_webhook(os.environ['ACCESS_TOKEN'], {
    'endPoint': 'https://my-saas.example.com/hooks/happycolis',
    'type': 'delivery_order/completed',
    'headers': {'X-Api-Key': 'my-saas-api-key'},
})
print(f"Webhook registered: {webhook['id']}")

PHP

<?php
$mutation = <<<'GQL'
mutation OauthWebhookCreate($input: IntegrationWebhookInput!) {
  oauthWebhookCreate(input: $input) {
    id
    type
    health
    endPoint
  }
}
GQL;

$payload = json_encode([
    'query'     => $mutation,
    'variables' => [
        'input' => [
            'endPoint' => 'https://my-saas.example.com/hooks/happycolis',
            'type'     => 'delivery_order/completed',
            'headers'  => ['X-Api-Key' => 'my-saas-api-key'],
        ],
    ],
]);

$ch = curl_init('https://api-v3.happycolis.com/graphql');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . getenv('ACCESS_TOKEN'),
    ],
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

echo 'Webhook registered: ' . $result['data']['oauthWebhookCreate']['id'];

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func createOauthWebhook(accessToken string, input map[string]any) (map[string]any, error) {
	mutation := `
		mutation OauthWebhookCreate($input: IntegrationWebhookInput!) {
			oauthWebhookCreate(input: $input) {
				id
				type
				health
				endPoint
			}
		}`

	body, _ := json.Marshal(map[string]any{
		"query":     mutation,
		"variables": map[string]any{"input": input},
	})

	req, _ := http.NewRequest("POST", "https://api-v3.happycolis.com/graphql", bytes.NewBuffer(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+accessToken)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	var result map[string]any
	json.NewDecoder(resp.Body).Decode(&result)

	if errs, ok := result["errors"]; ok {
		return nil, fmt.Errorf("graphql error: %v", errs)
	}
	data := result["data"].(map[string]any)
	return data["oauthWebhookCreate"].(map[string]any), nil
}

func main() {
	webhook, err := createOauthWebhook(os.Getenv("ACCESS_TOKEN"), map[string]any{
		"endPoint": "https://my-saas.example.com/hooks/happycolis",
		"type":     "delivery_order/completed",
		"headers":  map[string]any{"X-Api-Key": "my-saas-api-key"},
	})
	if err != nil {
		panic(err)
	}
	fmt.Printf("Webhook registered: %s\n", webhook["id"])
}