API Docs v1 api.hubiss.com.br

Webhooks

Receba notificações de novos pedidos e alterações sem precisar de polling.

Em resumo
Webhook é o jeito certo de receber pedidos sem polling. Sua URL precisa responder 2xx em até 2 segundos.

Um webhook é um endpoint do seu sistema que a Hubiss chama quando um novo pedido entra ou quando um pedido muda. É o caminho recomendado para quem precisa alimentar um ERP.

Por que cadastrar um webhook?

Se você cadastra produtos por API, provavelmente tem um ERP para emitir nota fiscal. O webhook permite administrar os pedidos dentro do ERP sem copiar informação manualmente.

Tópicos de notificação

Tópico Quando é disparado Situação
orders Novo pedido na plataforma ou alteração vinda do marketplace Ativo
products Alteração de status ou estoque do produto Ainda não implantado

Corpo enviado (POST para o seu endpoint)

JSONjson
{
    "userId": "1",
    "topic": "orders",
    "resource": "orders/123",
    "attempt": 1
}
Campo Descrição Exemplo Opções
userId Identificador do usuário responsável pelo registro 1 varia
topic Tipo de notificação enviada orders orders · products
resource Caminho completo para recuperar o registro depois orders/123 varia
attempt Número da tentativa atual de entrega 1 varia
Entregas e retentativas
Em caso de falha a Hubiss tenta novamente até 10 vezes. Responda sempre 2xx o mais rápido possível e processe o evento de forma assíncrona do seu lado.

Boas práticas no seu endpoint

  • Valide o payload e responda 200 mesmo que decida ignorar o evento.
  • Use attempt para detectar reenvios e aplicar idempotência.
  • Busque o registro pelo resource antes de processar, para garantir o estado atual.
GET /webhooks
Listar Webhooks

Listar todos os Webhooks cadastrados.

StatusQuando aconteceCorpo
401 401 —
Resposta
json
{
    "data": [
        {
            "id": 100,
            "url": "http://renner.biz/?5200",
            "created_at": "2022-03-22 23:26:10",
            "updated_at": "2022-03-22 23:26:10",
            "topics": [
                "orders",
                "products"
            ]
        },
        {
            "id": 88,
            "url": "http://www.hodkiewicz.net/voluptas-consequatur-quis-sequi-veritatis?6198",
            "created_at": "2022-03-22 23:26:10",
            "updated_at": "2022-03-22 23:26:10",
            "topics": [
                "orders",
                "products"
            ]
        },
        {
            "id": 86,
            "url": "http://mertz.info/sit-aliquid-fugiat-quod-laboriosam-sit-suscipit-dolorem.html?324",
            "created_at": "2022-03-22 23:26:10",
            "updated_at": "2022-03-22 23:26:10",
            "topics": [
                "orders",
                "products"
            ]
        },
        {
            "id": 77,
            "url": "http://howe.com/occaecati-quis-laudantium-et-eveniet.html?4690",
            "created_at": "2022-03-22 23:26:10",
            "updated_at": "2022-03-22 23:26:10",
            "topics": [
                "orders",
                "products"
            ]
        },
        {
            "id": 76,
            "url": "http://koelpin.com/itaque-voluptas-dolorem-voluptates-est?9455",
            "created_at": "2022-03-22 23:26:10",
            "updated_at": "2022-03-22 23:26:10",
            "topics": [
                "orders",
                "products"
            ]
        },
        {
            "id": 68,
            "url": "https://champlin.com/sed-facilis-itaque-molestiae-quia-enim-eum-velit.html?1598",
            "created_at": "2022-03-22 23:26:10",
            "updated_at": "2022-03-22 23:26:10",
            "topics": [
                "orders",
                "products"
            ]
        },
        {
            "id": 60,
            "url": "http://www.mills.com/aperiam-neque-voluptatem-aliquam-rerum-enim?4754",
            "created_at": "2022-03-22 23:26:10",
            "updated_at": "2022-03-22 23:26:10",
            "topics": [
                "orders",
                "products"
            ]
        },
        {
            "id": 59,
            "url": "http://www.conn.info/quo-mollitia-consequatur-dolores-repudiandae-quod-iste?5206",
            "created_at": "2022-03-22 23:26:10",
            "updated_at": "2022-03-22 23:26:10",
            "topics": [
                "orders",
                "products"
            ]
        },
        {
            "id": 51,
            "url": "https://schamberger.org/assumenda-sapiente-culpa-a-ut-ipsa-consequatur-sunt.html?1804",
            "created_at": "2022-03-22 23:26:10",
            "updated_at": "2022-03-22 23:26:10",
            "topics": [
                "orders",
                "products"
            ]
        },
        {
            "id": 31,
            "url": "http://www.cruickshank.com/est-pariatur-aut-nulla-et-ea-non-hic.html?8985",
            "created_at": "2022-03-22 23:26:10",
            "updated_at": "2022-03-22 23:26:10",
            "topics": [
                "orders",
                "products"
            ]
        },
        {
            "id": 8,
            "url": "http://www.watsica.com/placeat-temporibus-dolor-alias-iure-dolores-rerum-autem?4659",
            "created_at": "2022-03-22 23:26:10",
            "updated_at": "2022-03-22 23:26:10",
            "topics": [
                "orders",
                "products"
            ]
        },
        {
            "id": 3,
            "url": "http://www.keebler.com/sunt-voluptas-earum-ratione-dolorum-velit-et-vero.html?6457",
            "created_at": "2022-03-22 23:26:10",
            "updated_at": "2022-03-22 23:26:10",
            "topics": [
                "orders",
                "products"
            ]
        }
    ],
    "links": {
        "first": "https://hubiss.dev/api/v1/webhooks?page=1",
        "last": "https://hubiss.dev/api/v1/webhooks?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "active": false
            },
            {
                "url": "https://hubiss.dev/api/v1/webhooks?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "active": false
            }
        ],
        "path": "https://hubiss.dev/api/v1/webhooks",
        "per_page": 15,
        "to": 12,
        "total": 12
    }
}
{
    "error": "Unauthorized"
}
Exemplo
curl --request GET \
     --url 'https://api.hubiss.com.br/v1/webhooks' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer SEU_TOKEN'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('SEU_TOKEN')
    ->acceptJson()
    ->get('https://api.hubiss.com.br/v1/webhooks');

$response->json();
const response = await fetch('https://api.hubiss.com.br/v1/webhooks', {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN'
    }
});

const data = await response.json();
import requests

response = requests.GET(
    'https://api.hubiss.com.br/v1/webhooks',
    headers={'Authorization': 'Bearer SEU_TOKEN', 'Accept': 'application/json'},
)

print(response.json())
O token é usado apenas nesta requisição e não é armazenado.
POST /webhooks
Cadastrar Webhook
StatusQuando aconteceCorpo
401 401 —
422 422 —
CampoTipoDescrição
url * string
topics * array
Corpo enviado (JSON) json
{
    "url": "http://www.meusistema.com/callback/hubiss",
    "topics": [
        "orders"
    ]
}
Resposta
json
{
    "data": {
        "id": 102,
        "url": "http://www.meusistema.com/callback/hubiss",
        "created_at": "2022-03-23 16:21:43",
        "updated_at": "2022-03-23 16:21:43",
        "topics": [
            "orders"
        ]
    },
    "success": true,
    "message": "Register Successfull Inserted"
}
{
    "error": "Unauthorized"
}
{
    "success": false,
    "message": "Validation errors",
    "data": {
        "url": [
            "The url field is required."
        ],
        "topics": [
            "The topics field is required."
        ]
    }
}
Exemplo
curl --request POST \
     --url 'https://api.hubiss.com.br/v1/webhooks' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer SEU_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{    "url": "http://www.meusistema.com/callback/hubiss",    "topics": [        "orders"    ]}'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('SEU_TOKEN')
    ->acceptJson()
    ->withBody("{\n    \"url\": \"http:\/\/www.meusistema.com\/callback\/hubiss\",\n    \"topics\": [\n        \"orders\"\n    ]\n}", 'application/json')
    ->post('https://api.hubiss.com.br/v1/webhooks');

$response->json();
const response = await fetch('https://api.hubiss.com.br/v1/webhooks', {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
    "url": "http://www.meusistema.com/callback/hubiss",
    "topics": [
        "orders"
    ]
})
});

const data = await response.json();
import requests

response = requests.POST(
    'https://api.hubiss.com.br/v1/webhooks',
    headers={'Authorization': 'Bearer SEU_TOKEN', 'Accept': 'application/json'},
    json={
    "url": "http://www.meusistema.com/callback/hubiss",
    "topics": [
        "orders"
    ]
},
)

print(response.json())
O token é usado apenas nesta requisição e não é armazenado.
GET /webhooks/{webhookId}
Recuperar Webhook

Retorna o Webhook com essa id

StatusQuando aconteceCorpo
401 401 —
404 404 —
Nome Local Tipo Descrição
webhookId * path integer
Resposta
json
{
    "url": "http://www.meusistema.com/callback/hubiss",
    "topics": [
        "orders"
    ]
}
{
    "error": "Unauthorized"
}
{
    "error": "Resource 9999 not found"
}
Exemplo
curl --request GET \
     --url 'https://api.hubiss.com.br/v1/webhooks/WEBHOOKID' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer SEU_TOKEN'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('SEU_TOKEN')
    ->acceptJson()
    ->get('https://api.hubiss.com.br/v1/webhooks/WEBHOOKID');

$response->json();
const response = await fetch('https://api.hubiss.com.br/v1/webhooks/WEBHOOKID', {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN'
    }
});

const data = await response.json();
import requests

response = requests.GET(
    'https://api.hubiss.com.br/v1/webhooks/WEBHOOKID',
    headers={'Authorization': 'Bearer SEU_TOKEN', 'Accept': 'application/json'},
)

print(response.json())
O token é usado apenas nesta requisição e não é armazenado.
PUT /webhooks/{webhookId}
Atualizar Webhook
StatusQuando aconteceCorpo
401 401 —
404 404 —
422 422 —
Nome Local Tipo Descrição
webhookId * path integer
CampoTipoDescrição
url * string
topics * array
Corpo enviado (JSON) json
{
    "url": "http://www.meusistema.com/callback/hubiss_alterado",
    "topics": [
        "orders"
    ]
}
Resposta
json
{
    "data": {
        "id": 102,
        "url": "http://www.meusistema.com/callback/hubiss_alterado",
        "created_at": "2022-03-23 16:21:43",
        "updated_at": "2022-03-23 16:21:43",
        "topics": [
            "orders"
        ]
    },
    "success": true,
    "message": "Register Successfull Updated"
}
{
    "error": "Unauthorized"
}
{
    "error": "Resource 99999 not found"
}
{
    "success": false,
    "message": "Validation errors",
    "data": {
        "url": [
            "The url field is required."
        ],
        "topics": [
            "The topics field is required."
        ]
    }
}
Exemplo
curl --request PUT \
     --url 'https://api.hubiss.com.br/v1/webhooks/WEBHOOKID' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer SEU_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{    "url": "http://www.meusistema.com/callback/hubiss_alterado",    "topics": [        "orders"    ]}'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('SEU_TOKEN')
    ->acceptJson()
    ->withBody("{\n    \"url\": \"http:\/\/www.meusistema.com\/callback\/hubiss_alterado\",\n    \"topics\": [\n        \"orders\"\n    ]\n}", 'application/json')
    ->put('https://api.hubiss.com.br/v1/webhooks/WEBHOOKID');

$response->json();
const response = await fetch('https://api.hubiss.com.br/v1/webhooks/WEBHOOKID', {
    method: 'PUT',
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
    "url": "http://www.meusistema.com/callback/hubiss_alterado",
    "topics": [
        "orders"
    ]
})
});

const data = await response.json();
import requests

response = requests.PUT(
    'https://api.hubiss.com.br/v1/webhooks/WEBHOOKID',
    headers={'Authorization': 'Bearer SEU_TOKEN', 'Accept': 'application/json'},
    json={
    "url": "http://www.meusistema.com/callback/hubiss_alterado",
    "topics": [
        "orders"
    ]
},
)

print(response.json())
O token é usado apenas nesta requisição e não é armazenado.
DELETE /webhooks/{webhookId}
Excluir Webhook

Exclui o Webhook com essa id

StatusQuando aconteceCorpo
401 401 —
404 404 —
Nome Local Tipo Descrição
webhookId * path integer
Resposta
json
204
{
    "error": "Unauthorized"
}
{
    "error": "Resource 9999 not found"
}
Exemplo
curl --request DELETE \
     --url 'https://api.hubiss.com.br/v1/webhooks/WEBHOOKID' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer SEU_TOKEN'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('SEU_TOKEN')
    ->acceptJson()
    ->delete('https://api.hubiss.com.br/v1/webhooks/WEBHOOKID');

$response->json();
const response = await fetch('https://api.hubiss.com.br/v1/webhooks/WEBHOOKID', {
    method: 'DELETE',
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN'
    }
});

const data = await response.json();
import requests

response = requests.DELETE(
    'https://api.hubiss.com.br/v1/webhooks/WEBHOOKID',
    headers={'Authorization': 'Bearer SEU_TOKEN', 'Accept': 'application/json'},
)

print(response.json())
O token é usado apenas nesta requisição e não é armazenado.

Erros comuns

Sintoma Causa provável O que fazer
Nenhum evento chega URL não responde 2xx Testar a URL e responder rápido
Eventos duplicados Reenvio por tentativa Deduplicar por resource + attempt
Próximo passo