Como os webhooks funcionam no HireHop

O HireHop pode enviar uma mensagem com dados para outros aplicativos quando determinados eventos são acionados no HireHop. Essa mensagem é chamada de webhook que envia automaticamente os dados relevantes para o local necessário.

WbhooksO que é um webhook?

Um webhook envia/envia uma mensagem, com dados anexados à mensagem, quando coisas específicas acontecem no HireHop (um evento). Os webhooks são enviados via HTTP (chama um endereço da web) e são uma forma de enviar dados para outros aplicativos em tempo real. Os webhooks entregam os dados relevantes para aplicativos específicos à medida que eles acontecem, o que significa que o aplicativo receptor obtém os dados imediatamente após a ocorrência do evento, o que é muito mais eficiente e rápido do que pesquisar alterações de dados.

Os webhooks do HireHop podem ser usados ​​para se comunicar diretamente com outros aplicativos ou ser enviados para um conector como o Zapier, que pode ser feito para formatar os dados e fazer as chamadas de API necessárias de volta ao HireHop ou a outro aplicativo.

Configurando um webhook

No HireHop, vá para “Configurações” e clique na guia “Configurações da empresa” e no botão “Webhooks” na parte superior da página. Na janela pop-up, clique no botão “Novo” e adicione o URL para o qual a mensagem do webhook deve ser enviada e selecione todos os webhook aos quais você deseja que o URL responda. Você pode adicionar quantos webhooks quiser, mas deve limitá-los apenas aos necessários aos quais a URL específica responderá.

Um webhook HireHop enviará dados para seu endpoint de URL como JSON e conterá os dados a seguir ou semelhantes.

{
    "time": "2022-03-29 07:50:42",
    "user_id": 1,
    "user_name": "John Smith",
    "user_email": "john@email.com",
    "company_id": 1,
    "export_key": "22u43mrjwe7u",
    "event": "invoice.status.updated",
    "data": { ... },
    "changes": {
        "FIELD_NAME": {
            "from": "velho",
            "to": "novo"
        }, ...
    }
}

No exemplo JSON acima, os campos a seguir são:

  • time” é a hora UTC e a data em que o webhook foi enviado.
  • user_id” é o ID do usuário que acionou o evento.
  • user_name” é o nome do usuário.
  • company_id” é o identificador de número exclusivo da empresa para a qual o usuário trabalha.
  • export_key” é o valor da chave de exportação nas configurações da empresa que pode ser usada como verificação de segurança.
  • event” é o nome do evento de webhook que foi acionado.
  • data” são os dados que pertencem ao evento webhook.
  • changes” são os campos que mudaram, sendo o que eram para o que foram alterados.

O HireHop não aguardará uma resposta do URL chamado ou relatará um erro HTTP ao chamá-lo.

O código PHP de exemplo para um endpoint de URL para capturar os dados do webhook seria:

<?php
	// Obtenha os dados JSON
	$postdata = file_get_contents('php://input');
	// Converter dados JSON em um objeto
	$data_str = json_decode($postdata);
?>

 

Posted in API

HireHop Rest API – Guia de primeiros passos

HireHop é construído em cima de uma API, o que significa que qualquer coisa que você vê o HireHop fazer, você também pode realizar usando a API abrangente. Tudo o que você precisa para acessar a API Rest é um token de usuário aplicado como GET ou POST ao endpoint de URL relevante.

Tokens API

Para gerar um token de API, vá para a página “Configurações” e selecione a guia “Usuários”. Selecione ou crie um usuário e, enquanto esse usuário específico estiver selecionado, clique no botão “Menu” e na opção “Token de API” para gerar um token. O token será exibido e pode ser copiado para a área de transferência usando o botão de cópia.

O token se tornará inválido se você alterar o e-mail ou a senha do usuário selecionado ou, posteriormente, efetuar login nesse usuário. Para evitar que isso aconteça, você deve criar um usuário de API dedicado e, por segurança, dar a ele as permissões relevantes, restringindo-o de qualquer coisa para a qual não esteja usando a API.

Por motivos de segurança, você não deve usar o token no código JavaScript de front end, ele deve ser usado apenas no lado do servidor, pois se um hacker obtiver o token, ele pode alterar e acessar seus dados no HireHop, portanto, mantenha seu token em segredo. Se o seu token vazar, basta alterar a senha do usuário da API e gerar um novo token.

Usando um Token

Um token deve ser definido como um parâmetro GET ou POST que é chamado de “token”. Por exemplo, para carregar os dados do trabalho para o número 52, HireHop chamará o endpoint da API:

https://myhirehop.com/php_functions/job_refresh.php?job=52

Se você deseja chamar o mesmo endpoint usando um token, o URL seria:

https://myhirehop.com/php_functions/job_refresh.php?job=52&token=dqwejk5GVT65909bHHBN7922pq5hxjm%207hmn

Lembre-se de que, ao passar o token via GET (um parâmetro de URL como acima), você deve codificar o token primeiro usando uma ferramenta como https://meyerweb.com/eric/tools/dencoder.

Dados de Postagem

Para criar ou editar dados no HireHop, você deve usar um POST. Ao postar dados, você deve definir apenas os campos que deseja alterar, por exemplo, para criar ou editar um trabalho usando o endpoint https://myhirehop.com/php_functions/job_save.php, definindo o parâmetro “trabalho” para “0 “ou sua omissão criará um novo trabalho, qualquer outra coisa editará o número do trabalho relevante. Portanto, para editar o nome da empresa no trabalho número 52, os dados da postagem devem ser:

{
"job" : 52,
"name" : "New Name",
"token" : "dqwejk5GVT65909bHHBN7922pq5hxjm=-7hmn"
}

Pontos de extremidade da API

Muitos endpoints da API estão documentados na documentação da API, com muitos outros a seguir.  Para estabelecer o terminal para uma tarefa, no aplicativo HireHop, use o console do navegador para inspecionar as chamadas de rede e quais parâmetros estão definidos. Um guia extenso para os endpoints de URL será publicado em breve.

Limites de taxa

O HireHop permite a cada usuário 60 solicitações de conexão em um período de 1 minuto. Se houver mais de 60, um erro “Aviso de segurança, muitas transações” (327) será retornado.

Posted in API

Custom Fields – HireHop API

You can have an unlimited number of custom fields in HireHop specific to each record, a record being a job, project, test/service, asset, etc.  All custom fields can be used in documents, as long as they exist, otherwise they will just be blank.

Currently custom fields are only fully supported in Jobs and Projects. Custom fields can only be used using plugins.

Custom Fields Structure

When fetching a custom field for the currently edited record, there is a function called _get_custom_field_value(field) which will return NULL if the field is not set, a string, or a JavaScript object, depending on how you saved it.

You probably should save custom fields as a JavaScript object (like JSON) in the following format for more printing control, as if it is just a string, HireHop will treat it as a string:

"field_name" :
{
"value"  : "The value of the field",
"type"   : "The field type, default is text, it can also be number, currency, text, date, html and array"
"format" : "For date type only, eg "ddd, dddddd tt" // = "Mon, January 1 2017 12:00"
}

  • value is the value of the field in any format.
  • type tells HireHop how the field should be treated when merging it into a document. An array field will be displayed as JSON.
  • format tells HireHop how to format the field in the document, currently only available dates and is dependent on the users settings and how their date and time formats are set:
    • dddddd for a long date (like January 1 2018)
    • ddddd for a short date (like 01/01/2018)
    • dddd for the day of the week (like Monday)
    • ddd for the short day of the week (like Mon)
    • tt for the time (like 12:36 am).

The format part is only needed for dates and if it is not set, nothing will show.  You can merge formats together and add separators, for instance you can use dddd, dddddd tt which will give “Monday, January 1 2018 12:00” if the user has set a date order as day month year. The value for a date type must be stored in the yyyy-mm-dd hh:mm format.

If you just save the field as a string and not a JavaScript object, that’s fine, HireHop will just treat it as a string.  Saving your custom fields as a JavaScript object will give you greater control, especially when HireHop prints them in a document.

Saving The Custom Fields

On all edit forms that support custom fields, there is a function called _save_custom_field_value(field, value).  This stores your fields to be saved later.  If you can’t find the function, please contact us.

Please note, that all changes must be written prior to saving.

When the custom fields are saved, they are merged with the existing fields, and any new fields passed with the same name as any existing ones, the new values will be set.

When saving the custom fields, for example using /php_functions.job_save.php directly as an API call, only parameters set will be updated, so if you only set the custom_fields post parameter, only the custom fields will change, all the other fields will stay as is.

Printing Custom Fields

All custom fields can be incorporated into documents just like normal fields and are prefixed with a single “_” (underscore) character.  For example, for a custom field in a job called “field_name”, you would load it by using the merge field “job:_field_name“.

Naming Custom Fields

Some custom fields in documents merge fields together, for example tests merge with an asset in some document fields, so be careful not to use the same field name in an asset and a test.  Also, other plugins maybe added in the future written by yourself or from another source, so add a prefix that denominates you, for example plugins written HireHop by use the “hh_” prefix, so a field written in a plugin by us might be called “hh_NewName”.  Field names in document merges are not case sensitive, but they obviously are in JavaScript.

Searchable Custom Field

There is an additional field called CUSTOM_INDEX, that can be used for searching, filtering and listed in search results.  The field is a 45 character string value that can be set to NULL. To enable the field to be shown in the search results on the home page, change the allSearchCols global JavaScript variable by adding CUSTOM_INDEX to it:

if(allSearchCols.constructor===Array && doc_type==0 ) {
allSearchCols.push("CUSTOM_INDEX");
}

There is also a language setting for the custom field displayed name:

if(typeof(lang["customIndexTxt"])=="undefined" || lang["customIndexTxt"]=="") {
lang["customIndexTxt"] = "Custom field name";
}

The reason for the testing for undefined or blank above is just in case the user has set it in the language.

You can use the custom searchable field in the page by adding a lookup in the page or the editor.  On jobs there is a hidden tile that displays the  CUSTOM_INDEX field and can be shown and utilised like so in a plugin:

$("#job_tile_custom_index")
.show()
.click(function() {
window.open("https://www.my_external_app.com?id="+job_data["CUSTOM_INDEX"],"newwindow");
});

To save the CUSTOM_INDEX field in the relevant edit widget, using a custom plugin you can add a form element into the edit widget, for example like so:

// This adds the CUSTOM_INDEX field into the job edit widget
if(typeof($.custom.job_edit)!="undefined") {
// Redefine job_edit, move name to after telephone
$.widget("custom.job_edit", $.custom.job_edit, {
_init_main: function() {
// Call the old _init_main
this._super(arguments);
// Add an extra edit in the job edit
var table = this.default_disc.closest("table");
var tr = $("<tr>").appendTo( table);
$("<td>", { html: lang.customIndexTxt+ " :" }).appendTo(tr);
$("<input>", {
"name" : "custom_index", // Parameter to pass when saving
"class" : "data_cell",   // Setting class to data_cell tells HireHop it is a standard data field
"data-field" : "CUSTOM_INDEX", // Name of the field
"maxlength" : 45         // The CUSTOM_INDEX has a maximum length of 45 characters
})
.appendTo( $("<td>").appendTo(tr) );
// Change the memo height to compensate
this.job_edit_memo.height(110);
}
});
}

The CUSTOM_INDEX field is called xxx:custom_index in the document and is passed as a string into the document.

Global Custom Fields

Occasionally you might want to store a global counter, etc. for the whole company.  To read and store global custom fields use /php_functions/custom_fields_global_load.php and /php_functions/custom_fields_global_save.php.  Saving the data, you need to pass either a json string or json array:

$("#saving_dialog").dialog("open");
// This adds the CUSTOM_INDEX field into the job edit widget
$.ajax({
url: "/php_functions/custom_fields_global_save.php",
type: "post",
dataType: "json",
data: {
"fields":{"my_field":"any type of value"}
// or a json string
// "field":'{"my_field":"any type of value"}'
},
success: function(data)
{
$("#saving_dialog").dialog("close");
// HireHop reported an error
if(typeof(data.error) !== "undefined")
error_message(isNaN(parseInt(data.error)) ? data.error : lang.error[data.error]);
else
{
// All good, "data" is a javascript object (JSON) of all global custom fields
}
},
// Handle an http error
error: function(jqXHR, textStatus, errorThrown)
{
$("#saving_dialog").dialog("close");
error_message(lang.error[1]+" ("+errorThrown+").");
}
});

Posted in API

Cross Domain Fonts CORS – Fonte CSS não carregando

Muitos usuários criaram alguns documentos incríveis para uso no HireHop, utilizando HTML5, JavaScript e funcionalidade CSS. Para esses documentos, os usuários às vezes precisam de uma fonte especial que eles armazenam em seu servidor; no entanto, às vezes a fonte parece não funcionar no documento HireHop. A razão para isso é devido às restrições de Cross-Origin Resource Sharing (CORS) nos navegadores.

As Fontes não Narregam nos Documentos

A maioria dos navegadores da web não permite solicitações de domínio cruzado, isso é devido à mesma política de segurança de origem. Isso significa que, às vezes, ao usar fontes da web de outro domínio pode causar erros e a fonte não carrega no navegador ou em documentos HireHop.

<style type="text/css">
@font-face {
    font-family: 'OpenSans';
    src: url('https://my_server.com/fonts/OpenSans.woff2') format('woff2');
}
html, body{
    font: normal 16px OpenSans, sans-serif;
}
</style>

A Solução

Para corrigir as restrições de origem cruzada para suas fontes, a resposta do servidor remoto que hospeda os arquivos de fonte deve incluir o cabeçalho Access-Control-Allow-Origin.

Se você estiver usando serviços de fontes como Typekit ou Google Fonts, ou talvez redes de distribuição de conteúdo como BootstrapCDN, CdnJS ou JsDelivr para carregar suas fontes preferidas, você não precisa fazer nada, porque o cabeçalho Access-Control-Allow-Origin é já enviado em seu cabeçalho de resposta.

Apache

Para configurar um servidor da web Apache, coloque o seguinte código no arquivo httpd.conf ou .htaccess.

  1. Adicione os cabeçalhos de tipo MIME no Apache:
    AddType application/vnd.ms-fontobject    .eot
    AddType application/x-font-opentype      .otf
    AddType image/svg+xml                    .svg
    AddType application/x-font-ttf           .ttf
    AddType application/font-woff            .woff
    AddType application/font-woff2           .woff2
    
  2. Ative o compartilhamento de recursos de origem cruzada (CORS) no Apache para os tipos MIME:
    <IfModule mod_headers.c>
      <FilesMatch ".(eot|otf|svg|ttf|woff2?)$">
        Header set Access-Control-Allow-Origin "*"
      </FilesMatch>
    </IfModule>
    

NGINX

Para configurar um servidor da web NGINX, coloque o seguinte código em /etc/nginx/nginx.conf ou em seu arquivo /etc/nginx/conf.d/custom.conf personalizado.

  1. Adicione os cabeçalhos de tipo MIME no NGINX:
    application/vnd.ms-fontobject    eot;
    application/x-font-opentype      otf;
    image/svg+xml                    svg;
    application/x-font-ttf           ttf;
    application/font-woff            woff;
    application/font-woff2           woff2;
    
  2. Ative o compartilhamento de recursos de origem cruzada (CORS) no NGINX para os tipos MIME:
    location ~* .(eot|otf|svg|ttf|woff|woff2)$ {
        add_header Access-Control-Allow-Origin *;
    }
    

IIS

Para configurar o Microsoft IIS, adicione o seguinte código ao arquivo web.config system.webServer.

  • Habilitar compartilhamento de recursos de origem cruzada (CORS) no IIS
    <system.webServer>
      <httpProtocol>
        <customHeaders>
          <add name="access-control-allow-origin" value="*" />
          <add name="access-control-allow-headers" value="content-type" />
        </customHeaders>
      </httpProtocol>
    </system.webServer>
    

PHP

Se você não pode alterar as configurações do servidor, você sempre pode usar o PHP para entregar o arquivo de fonte.

  • Use um arquivo de script de servidor em vez de um arquivo de fonte física
    <style type="text/css">
    @font-face {
        font-family: 'OpenSans';
        src: url('https://my_server.com/fonts/OpenSans.php') format('woff2');
    }
    html, body{
        font: normal 16px OpenSans, sans-serif;
    }
    </style>
    
  • Como corrigir problemas de cross-domain @font-face com PHP
    <?php
    // fonts.php
    header('Access-Control-Allow-Origin: *');
    header('Content-Type: application/font-woff2');
    echo @file_get_contents('/fonts/OpenSans.woff2');
    ?>
    
Posted in API