Webhooks (events) at Stockcrowd.

Let us explain first ?

What are webhooks?

Simply put, webhooks are events that trigger actions. They get their name from the fact that they function as "hooks" for programmes on the Internet and are almost always used for communication between systems. They are the easiest way to issue a warning when a specific event happens on another system.

Below is an introduction and explanation of where they are found and how you can use them within Stockcrowd.

This guide includes the different types of events that StockCrowd triggers and which are used to integrate with web services that retrieve the data associated with each of the events.

Events - Stockcrowd

Types of events

Below is a list of the types of events available in the system:

Payment request confirmed -> This event is triggered when the donation has been confirmed.
Registration confirmed -> This event is triggered when the registration, through a signature form, is confirmed
Reward purchased -> This event is triggered when the reward has been purchased

*There are two events that will be available during 2021:

Abandoned cart -> This event is triggered when a donor has not completed the donation, but we have their details.
Recurrency confirmed -> This event is triggered when the system confirms the amount of a recurring donation

Events Back-Office

The event management back-office is located under the 'Events' menu, in the 'Organisation' section of the StockCrowd back-office.

The steps to define an event are as follows:

Select the type of event to configure
Configure the notification, via url or email
Activate the notification

Once the notification is activated the StockCrowd software will launch an event by placing the event data in the configured url or email.

Data type

The encoding type for any event is UTF-8.

For a Confirmed Payment Request event the associated fields are as follows:

Section title	Description	Length	Format	Example Data	Mandatory
EVENT	Event type	100	Char	INVERSOR_PAYMENT_SUCCEEDED	Y
EVENT_ID	Unique identifier of the triggered event	255	Char	be4fceab-1ff8-4ab8-ad5b-4e711be88766	Y
FECHA	Registration date	20	Date	2016-04-31 13:00:14	Y
EMAIL	Email account used in registration	255	varChar	user1@domain1.com	Y
NOMBRE	Name used by the user in the registration process	255	Char	Pedro	Y
APELLIDOS	Surname used by the user in the registration process (Used in forms where the second surname is not required)	255	Char	Duque	Y
CAMPAIGN_TITULO	Campaign title	255	Char	Cohete a la luna	Y
PRIMER_APELLIDO	First surname used by the user in the registration process (Used in forms where the second surname is required)	255	Char	Duque	Y
SEGUNDO_APELLIDO	Second last name used by the user in the registration process (Used in forms where the second last name is required)	255	Char	Pérez	N
PREFIJO_TELEFONO	Telephone prefix entered by the user	5	Char	+34	N
ID_SOLICITUD	Request Unique Identifier (StockCrowd)	20	Num	456	Y
PASARELA_PAGO	Payment gateway used (PayPal, Stripe, Braintree, Lemon Way, Unnax)	100	Varchar	Stripe	Y
TRANSACTION_ID	Transaction identifier depending on the gateway (GATEWAY_PAYMENT)	255	Varchar	ch_1C9uu3BLADaPkItAiAGS1jCI	Y
ORDER_ID	StockCrowd payment request order number (unique). In case of successive requests, it should be checked that it has not been processed previously. This can happen when a contribution goes from anonymous to a registered user.	100	Varchar	879a9792-2b2f-49ca-bf03-1ab6d299e424	Y
IMPORTE	Amount in campaign currency	20	Num	49.95	Y
DIVISA	Currency (CAD, CHF, EUR, GBP, PLN, USD)	3	Varchar	EUR	Y
CAMPAIG_ID	Identifier of the campaign where the payment was made	12	Num	1234	Y
DOCUMENTO	Identity document NIE, DNI, CIF, PASSPORT. * Available if the user requests a SEPBLAC donation or validation certificate	20	Num	41125179Y	Y
TELEFONO	Telephone. * Available if the user requests a SEPBLAC donation or validation certificate	25	Num	612123123	N
DIRECCION	Address. * Available if the user requests a SEPBLAC donation or validation certificate	255	Varchar	C/ Bruc	N
CODIGO_POSTAL	Postal Code. * Available if the user requests a SEPBLAC donation or validation certificate	10	Varchar	08037	N
CIUDAD	City. * Available if the user requests a SEPBLAC donation or validation certificate	100	Varchar	Barcelona	N
PROVINCIA	Province. * Available if the user requests a SEPBLAC donation or validation certificate	50	Varchar	Barcelona	N
ID_PROVINCIA	Province Code. * Available if the user requests a SEPBLAC donation or validation certificate	10	Varchar	08	N
PAIS	Country. * Available if the user requests a SEPBLAC donation or validation certificate	105	Varchar	España	N
ID_PAIS	Country code. * Available if the user requests a SEPBLAC donation or validation certificate	2	Varchar	ES	N
TIPO_DOCUMENTO	Type of identity document (PASSPORT, DNI, CIF, NIF, NIE, OTHERS). * Available if the user requests a SEPBLAC donation or validation certificate	25	Varchar	DNI / CIF / NIE / OTRO	N
TIPO_PERSONA	F = Physical / J = Legal. * Available if the user requests a SEPBLAC donation or validation certificate	805	Varchar	F,N,P = Persona Física J,E = Persona jurídica	N
RAZON_SOCIAL	If TIPO_PERSONA = J (Legal). * Available if the user requests a SEPBLAC donation or validation certificate	255	Varchar	StockCrowd Fanraising S.L.	N
ACEPTA_PUBLICIDAD	S = Yes \| N = No	805	Varchar	S= Yes N= No	Y
POLITICA_PRIVACIDAD	S = Yes \| N = No	805	Varchar	S= Yes N= No	Y
USUARIO_REGISTRADO_PAYPAL	S = Yes \| N = No. If the payment has been made via PayPal and you have used a registered user account.	35	Varchar	S= Yes N= No	Y
NUMERO_PISO_LETRA	Número, piso y letra de la dirección del donante	150	Varchar	145, Entresuelo 2ª	N
IBAN	ex: # 135, E-2da	150	Varchar	ES55 1251 4161 1165 5165 7323	N
IBAN_TITULAR	IBAN_TITULAR - IBAN holder in payment data capture mode for CRMs	150	Varchar	Pedro Duque	N
PERIODICIDAD	Donation: ON TIME, MONTHLY, QUARTERLY, ANNUAL	30	Varchar	PUNTUAL, MENSUAL, TRIMESTRAL, ANUAL	N
UTM_SOURCE	UTM_SOURCE	200	Varchar	Google	N
UTM_MEDIUM	UTM_MEDIUM	200	Varchar	cpc	N
UTM_CAMPAIGN	UTM_CAMPAIGN	200	Varchar	spring_sale	N
UTM_TERM	UTM_TERM	200	Varchar	running+shoes	N
UTM_CONTENT	UTM_CONTENT	200	Varchar	logolink	N
EXTERNAL_ID	Value of the external identifier field of general campaign data	200	Varchar	SC45X22	N
CATEGORIA	General data category selector value of the campaign	200	Varchar	Ventas	N
SUB_CATEGORIA	Value of the sub-category field of general campaign data	200	Varchar	Electrodomésticos	N
SUBCUENTA_DEBE	Value of the sub-account field must of general campaign data	200	Varchar	45600	N
SUBCUENTA_HABER	Value of the sub-account field of general campaign data	200	Varchar	45700	N
TPV	Value of the general data POS field of the campaign	200	Varchar	45700	N
PAGO_RECURRENTE	S = Yes \| N = No. If it corresponds to a recurring charge	200	Varchar	S	N
PAGO_RECURRENTE_FCH_ALTA	Date the initial payment was made	200	Date	2016-04-31 13:00:14	N
PAGO_RECURRENTE_ORDER_ID	ORDER_ID referring to the initial payment	80	Varchar	879a9792-2b2f-49ca-bf03-1ab6d299e123	N
PAYMENT_TOKEN	Payment token for Stripe, Paypal, Sepa, Sofort operations	150	Varchar	tok_1CuGtMHCXJNKLeGQWDNzgDuG	N
SOLICITA_CERTIFICADO_DONACION	S = Yes \| N = No. If you have requested a donation certificate	805	Varchar	S	N
LOCALE	User language in IETF BCP 47 format	10	Varchar	es-ES	N
FUNDRAISER_NOMBRE	Name of the creator of the p2p campaign	255	Varchar	Jhon Doe	N

For a Confirmed Registration event the associated fields are as follows:

Section Title	Description	Length	Format	Example Data	Mandatory
EVENT	Event type	100	Char	INVERSOR_PAYMENT_SUCCEEDED	Y
EVENT_ID	Unique identifier of the triggered event	255	Char	be4fceab-1ff8-4ab8-ad5b-4e711be88766	Y
FECHA	Registration date of information associated with the reward from BOFAN	20	Date	2016-04-31 13:00:14	Y
EMAIL	Email account of the user who has purchased and completed the reward	255	varChar	user1@domain1.com	Y
NOMBRE	Name of the user who starts the payment process	255	Char	Pedro	Y
APELLIDOS	Surname of the user who made the payment	255	Char	Duque	Y
CAMPAIGN_TITULO	Campaign title	255	Char	Cohete a la luna	Y
PRIMER_APELLIDO	First last name used of the user who has made the payment (Used in forms where the second last name is required)	255	Char	Duque	Y
SEGUNDO_APELLIDO	Second last name used of the user who has made the payment (Used in forms where the second last name is required)	255	Char	Pérez	N
PREFIJO_TELEFONO	Telephone prefix entered by the user	5	Char	+34	N
ID_SIGNATURE	Unique signature identifier (StockCrowd)	20	Num	456	S
CAMPAIG_ID	Campaign identifier for the payment request	12	Num	1234	S
DOCUMENTO	Identity document NIE, DNI, CIF, PASSPORT. * Available if the user requests a SEPBLAC donation or validation certificate	20	Num	41125179Y	N
TELEFONO	Telephone. * Available if the user requests a SEPBLAC donation or validation certificate	25	Num	612123123	N
DIRECCION	Address. * Available if the user requests a SEPBLAC donation or validation certificate	255	Varchar	C/ Bruc	N
CODIGO_POSTAL	Postal Code. * Available if the user requests a SEPBLAC donation or validation certificate	10	Varchar	08037	N
CIUDAD	City. * Available if the user requests a SEPBLAC donation or validation certificate	100	Varchar	Barcelona	N
PROVINCIA	Province. * Available if the user requests a SEPBLAC donation or validation certificate	50	Varchar	Barcelona	N
ID_PROVINCIA	Province Code. * Available if the user requests a SEPBLAC donation or validation certificate	10	Varchar	08	N
PAIS	Country. * Available if the user requests a SEPBLAC donation or validation certificate	105	Varchar	España	N
ID_PAIS	Country code. * Available if the user requests a SEPBLAC donation or validation certificate	2	Varchar	ES	N
TIPO_DOCUMENTO	Type of identity document (PASSPORT, DNI, CIF, NIF, NIE, OTHERS). * Available if the user requests a SEPBLAC donation or validation certificate	25	Varchar	DNI / CIF / NIE / OTRO	N
TIPO_PERSONA	F = Physical / J = Legal. * Available if the user requests a SEPBLAC donation or validation certificate	805	Varchar	F,N,P = Persona Física J,E = Persona jurídica	N
RAZON_SOCIAL	If TIPO_PERSONA = J (Legal). * Available if the user requests a SEPBLAC donation or validation certificate	255	Varchar	StockCrowd Fanraising S.L.	N
ACEPTA_PUBLICIDAD	S = Yes \| N = No	805	Varchar	S= Sí N= No	Y
POLITICA_PRIVACIDAD	S = Yes \| N = No	805	Varchar	S= Sí N= No	Y
NUMERO_PISO_LETRA	ex: # 135, E-2da	150	Varchar	145, Entresuelo 2ª	N
ACEPTA_PUBLICACION_DATOS	S = Yes \| N = No	805	Varchar	S	Y
DESCRIPCION	In some cases, the description associated with a signature collection will be indicated.	255	Varchar	Carrer del Bruc 145	N

For a Purchased Reward event the associated fields are as follows:

Section Title	Description	Length	Format	Example Data	Mandatory
CHARSET	character encoding format		Char	UTF-8	Y
EVENT	Event type	100	Char	RECOMPENSA_SOLD	Y
EVENT_ID	Unique identifier of the triggered event	255	Char	be4fceab-1ff8-4ab8-ad5b-4e711be88766	Y
FECHA	Registration date	20	Date	2016-04-31 13:00:14	Y
ID_SOLICITUD_RECOMPENSA	Unique identifier of the triggered event	12	Num	121	Y
ID_RECOMPENSA_DETALLE	Registration date of information associated with the reward from BOFAN	12	Num	206	Y
EMAIL	Email account of the user who has purchased and completed the reward	255	Varchar	user1@domain1.com	Y
NOMBRE	Name of the user who starts the payment process	255	Char	Pedro o Pedro Duque	Y
ID_CAMPAIGN_RECOMPENSA	Requested Reward ID	255	Num	805	Y
TITULO_RECOMPENSA	Reward title	50	Varchar	Camiseta personalizada	Y
DIRECCION_RECOGIDA_ENTREGA	Pickup or delivery address	50	Varchar	Paseo de la castellana	N
ORDER_ID	Order number corresponding to the payment	36	Varchar	33a86073-ab05-4b1e-81b4-7bbcfdca31ed	Y
CANTIDAD	Quantity of units to be delivered	10	Num	3	Y

Data recovery web service configuration

Description of the process of event capture and validation via URL:

Event validation.
Events are validated by sending a request back to StockCrowd with all the parameters received in the POST. StockCrowd then compares the original event parameters with those received to ensure that the information is correct. If the validation process is correct, the system returns an "OK" in the body of the request and if, on the contrary, the validation is not correct, ERROR is returned in the body of the request.
Checking StockCrowd's response.
Confirmation to StockCrowd that the event has been processed correctly. If the response is correct, the data is validated and ready to be processed by the system managing the web service.
Confirmation to StockCrowd that the event has been successfully processed.
This is achieved by sending an "OK" as part of the response body. When StockCrowd sends an event to the URL configured in the notifications, the response is checked to ensure that the URL is actually managed by the domain owner. If the response is correct, the event is not sent again, but if it is not correct, the system will reprocess the event again by making two more requests with a time interval of 24 hours.

Validation URLs depending on the environment:

Testing platform (sandbox) : https://sandbox.stockcrowd.com/api/events/confirm

Production platform (producción): https://www.stockcrowd.com/api/events/confirm

Sample code for event validation

// *** STEP 805 ***

// endpoint de validación StockCrowd

$url = 'https://sandbox.stockcrowd.com/api/events/confirm'; // entorno de pruebas

// $url = 'https://www.stockcrowd.com/api/events/confirm'; // entorno de producción

// POST de vuelta a StockCrowd con todos los parámetros recibidos

$context = stream_context_create(array(

'http' => array(

'method' => 'POST',

'header' => 'Content-type: application/x-www-form-urlencoded',

'content' => http_build_query( $_POST )

)

, 'timeout' => 60

));

// *** STEP 2 ***

$resp = file_get_contents($url, FALSE, $context);

// si la respuesta a la validación por parte de StockCrowd es correcta

if ($resp=='OK'){

// código de integración propio del cliente (integración con otros sistemas del tipo CRM...)

} else {

// log para investigar peticiones que no han sido enviadas por StockCrowd

}

// *** STEP 3 ***

print_r('OK'); // indicar a StockCrowd que se ha procesado el evento

Categories

Categories