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
200mesmo que decida ignorar o evento. - Use
attemptpara detectar reenvios e aplicar idempotência. - Busque o registro pelo
resourceantes de processar, para garantir o estado atual.
GET
/webhooks
Listar Webhooks
Listar todos os Webhooks cadastrados.
Erros possíveis
| Status | Quando acontece | Corpo |
|---|---|---|
| 401 | 401 | — |
Respostas
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"
}
Exemplos por linguagem
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())
POST
/webhooks
Cadastrar Webhook
Erros possíveis
| Status | Quando acontece | Corpo |
|---|---|---|
| 401 | 401 | — |
| 422 | 422 | — |
Corpo da requisição
| Campo | Tipo | Descrição |
|---|---|---|
url
*
|
string |
|
topics
*
|
array |
Corpo enviado (JSON)
json
{
"url": "http://www.meusistema.com/callback/hubiss",
"topics": [
"orders"
]
}
Respostas
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."
]
}
}
Exemplos por linguagem
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())
GET
/webhooks/{webhookId}
Recuperar Webhook
Retorna o Webhook com essa id
Erros possíveis
| Status | Quando acontece | Corpo |
|---|---|---|
| 401 | 401 | — |
| 404 | 404 | — |
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
webhookId
*
|
path | integer |
Respostas
Resposta
json
{
"url": "http://www.meusistema.com/callback/hubiss",
"topics": [
"orders"
]
}
{
"error": "Unauthorized"
}
{
"error": "Resource 9999 not found"
}
Exemplos por linguagem
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())
PUT
/webhooks/{webhookId}
Atualizar Webhook
Erros possíveis
| Status | Quando acontece | Corpo |
|---|---|---|
| 401 | 401 | — |
| 404 | 404 | — |
| 422 | 422 | — |
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
webhookId
*
|
path | integer |
Corpo da requisição
| Campo | Tipo | Descrição |
|---|---|---|
url
*
|
string |
|
topics
*
|
array |
Corpo enviado (JSON)
json
{
"url": "http://www.meusistema.com/callback/hubiss_alterado",
"topics": [
"orders"
]
}
Respostas
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."
]
}
}
Exemplos por linguagem
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())
DELETE
/webhooks/{webhookId}
Excluir Webhook
Exclui o Webhook com essa id
Erros possíveis
| Status | Quando acontece | Corpo |
|---|---|---|
| 401 | 401 | — |
| 404 | 404 | — |
Parâmetros
| Nome | Local | Tipo | Descrição |
|---|---|---|---|
webhookId
*
|
path | integer |
Respostas
Resposta
json
204
{
"error": "Unauthorized"
}
{
"error": "Resource 9999 not found"
}
Exemplos por linguagem
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())
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
Siga para Fluxo completo de integração.